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

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 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

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 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

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

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

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

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

---

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 — Managing sources
• Knowledge Overview — Feature overview