> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge Translations

> Multi-language support for documents and portal UI

AGO supports multi-language knowledge bases through two translation systems: document content translations and portal UI translations. This guide covers both systems for creating a fully localized knowledge experience.

## Overview

The translation system enables:

* **Document Translations**: Translate knowledge articles into multiple languages
* **Connector-Native Translations**: Automatically import translations from multilingual sources (e.g., Zendesk)
* **Auto-Translation**: System-generated translations for languages not covered by native content
* **Portal Translations**: Localize the knowledge portal navigation and home page
* **Automatic Language Detection**: Content displays in the user's preferred language
* **Language-Aware Retrieval**: AI responses prioritize content in the user's language
* **Fallback Behavior**: Default content shown when translations are unavailable

## Supported Languages

Both translation systems support the following languages:

| Code | Language | Code | Language   |
| ---- | -------- | ---- | ---------- |
| `en` | English  | `pt` | Portuguese |
| `fr` | French   | `nl` | Dutch      |
| `es` | Spanish  | `pl` | Polish     |
| `de` | German   | `ru` | Russian    |
| `it` | Italian  | `ja` | Japanese   |
| `ko` | Korean   | `zh` | Chinese    |
| `ar` | Arabic   | `tr` | Turkish    |

> **Note**: Additional languages can be configured. Contact your administrator for details.

***

## Document Content Translations

Document translations allow you to provide knowledge articles in multiple languages, making your knowledge base accessible to international users.

### How It Works

```mermaid theme={null}
flowchart TD
    A[User Requests Document] --> B{User Language Set?}
    B -->|Yes| C{Translation Exists?}
    B -->|No| D[Use Default Language]
    C -->|Yes| E[Return Translation]
    C -->|No| D
    D --> F[Return Default Content]
```

### Translation Properties

Each document can have one translation per language. Translations include the following properties:

| Property          | Description                             |
| ----------------- | --------------------------------------- |
| Language          | ISO language code (e.g., `en`, `fr`)    |
| Title             | Translated document title               |
| Content           | Translated document body                |
| Related Questions | Translated related questions (optional) |
| Created At        | When the translation was created        |
| Updated At        | When the translation was last modified  |

> **Constraint**: Only one translation per language per document is allowed.

### Language Coverage

The document list in the admin interface shows language coverage for each document. Translation language pills (e.g., "EN", "FR", "DE") appear next to each document, allowing you to quickly see which languages are covered.

### Managing Document Translations

#### Via Admin Interface

1. Navigate to **Knowledge** → **Documents**
2. Select a document to translate
3. Click **Translations** tab to see all existing translations in a table view
4. Click **Add Translation** to open the translation builder
5. Select a target language, enter the translated title and content
6. Click **Save** to create the translation

To edit an existing translation, click its row in the table. To delete a translation, click the delete icon on the row (note: you cannot delete the default language translation).

To regenerate a translation using AI, click the regenerate icon on the row. This re-translates the document content from the source language using the current AI model, overwriting any manual edits. A confirmation dialog appears before the regeneration starts. This is useful when the original auto-translation was incomplete or when the source content has been updated.

> **ℹ️ NOTE**: Document translations can also be managed via API. See the [Public API v1 Reference](../api/public-api-v1) for endpoint details.

### Validation Rules

| Field             | Requirement                                   |
| ----------------- | --------------------------------------------- |
| Language          | Required, must not already exist for document |
| Title             | Required, cannot be empty                     |
| Content           | Required, cannot be empty                     |
| Related Questions | Optional                                      |

***

## Portal UI Translations

Portal translations localize the knowledge portal home page, including navigation items, descriptions, and display names.

### How It Works

```mermaid theme={null}
flowchart TD
    A[User Visits Portal] --> B[Detect User Language]
    B --> C{Translation Exists?}
    C -->|Yes| D[Display Translated Item]
    C -->|No| E[Display Default Item]
```

### Portal Item Properties

Each portal home page item has the following properties and can include translations for each supported language:

**Item Properties:**

| Property     | Description                         |
| ------------ | ----------------------------------- |
| Display Name | Default display name shown to users |
| Description  | Default description text            |
| URL          | Link destination                    |
| Icon         | Icon identifier                     |
| Order        | Display order on the page           |
| Active       | Whether the item is visible         |

**Translation Properties:**

| Property      | Description                          |
| ------------- | ------------------------------------ |
| Language Code | ISO language code (e.g., `fr`, `es`) |
| Display Name  | Translated display name              |
| Description   | Translated description               |

### Managing Portal Translations

#### Via Admin Interface

1. Navigate to **Knowledge** → **Home Items**
2. Click **Add New** or **Edit** on an existing item
3. Fill in the default display name and description
4. Click **Add Other Language**
5. Select target language and enter translations
6. Repeat for additional languages
7. Click **Save**

> **ℹ️ NOTE**: Portal items and translations can also be managed via API. See the [Public API v1 Reference](../api/public-api-v1) for endpoint details.

***

## Language Detection and Fallback

### User Language Detection

The system determines the user's language through:

1. User profile language setting
2. Browser language preference
3. Session language selection
4. Default organization language

### Fallback Behavior

| Scenario                               | Result                  |
| -------------------------------------- | ----------------------- |
| Translation exists for user's language | Display translation     |
| No translation, default exists         | Display default content |
| No default language set                | Use English (en)        |

### Switching Languages

When a user changes their language setting:

1. Portal items update immediately
2. Document content updates on next view
3. Search results respect the new language

***

## Best Practices

### Translation Workflow

1. **Create content in default language first**: Establish the source content
2. **Translate systematically**: Complete one language before starting another
3. **Maintain consistency**: Use glossaries for technical terms
4. **Review translations**: Have native speakers verify content

### Content Guidelines

* **Keep translations accurate**: Don't add or remove information
* **Preserve formatting**: Maintain headings, lists, and code blocks
* **Update simultaneously**: When source changes, update translations
* **Mark incomplete translations**: Use placeholders for pending work

### Performance Considerations

* Translations are loaded on-demand
* Frequently accessed translations may be cached
* Large knowledge bases benefit from lazy loading

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Issue: Translation not displaying">
    **Problem:** User sees default content instead of translation.

    **Solutions:**

    1. Verify translation exists for the user's language code
    2. Check user's language setting is correctly configured
    3. Verify translation is saved and active
    4. Clear browser cache and refresh
  </Accordion>

  <Accordion title="Issue: Unable to create translation">
    **Problem:** Translation creation fails with error.

    **Solutions:**

    1. Check if translation for that language already exists
    2. Verify all required fields are provided (title, content)
    3. Verify user has staff permissions
    4. Check for special characters or encoding issues
  </Accordion>

  <Accordion title="Issue: Portal items showing wrong language">
    **Problem:** Portal displays mix of languages.

    **Solutions:**

    1. Verify each item has translations for the target language
    2. Check default content is set for items without translations
    3. Review fallback language configuration
    4. Verify language detection is working correctly
  </Accordion>

  <Accordion title="Issue: Search returns wrong language results">
    **Problem:** Search shows documents in different languages.

    **Solutions:**

    1. Configure search to filter by language
    2. Verify documents have proper language tags
    3. Check search index includes language metadata

    ***
  </Accordion>
</AccordionGroup>

## How to Add a Language

1. Navigate to **Knowledge** > **Translations**
2. Click **Add Language**
3. Select the language from the dropdown
4. Choose the translation method:
   * **Automatic** — AGO translates content using AI
   * **Manual** — you provide translations yourself
5. If using automatic translation, review the output for accuracy
6. Publish the translations when ready

> **TIP**: Start with your highest-traffic language. Review AI translations for domain-specific terminology that may need manual correction.

***

## Related

* [Knowledge Source Management](./knowledge-source-management) — Managing sources
* [Knowledge Overview](./knowledge-overview) — Feature overview