> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/assistance/content-operations/languages.md).

# Languages

Setting up the languages an application serves, how end users get the right one, and translating content automatically or manually.

Userlane content can be published in multiple languages, so each end user sees guides, tooltips, announcements, and other content in their own language. You set up languages once, translate content automatically or by hand, and choose what happens when no language matches.

## Set up languages

Languages are managed in the portal under **Customize** > **Languages**. Each language has two parts: a display name and a language key.

The display name identifies the language in the portal. The language key is the code Userlane matches against the application's HTML language attribute and the user's browser language. Use a two-character code such as `en` or `de`, or a five-character code such as `en-us` or `de-at`, following the Internet Engineering Task Force (IETF) BCP 47 standard[^1]. The full list is in [Supported language codes](#supported-language-codes) below.

When you create a language, the **Copy-From** option lets you choose an existing language whose text is copied into the new one. This gives translators a starting point instead of empty fields.

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FYQyU2C3eFcRo0FQwYFpc%2Flanguages.png?alt=media&#x26;token=cb3cd893-3325-46c4-a42d-e79bee1421f9" alt="The Languages settings under Customize in the Userlane portal"><figcaption><p>Language settings in the portal.</p></figcaption></figure></div>

### Publish a language

You can publish a language in two ways. To publish it across all existing content at once, open the dot menu next to the language in the language settings and select **Publish**. Make sure translated text already exists first, because publishing an empty language shows blank content to end users.

To publish step by step, use the status and publish controls in the Editor[^2] at the chapter or guide level. Activate the language for both the chapter and the individual guide so that titles and step text all appear. This works well when you roll out a new language gradually.

{% hint style="danger" %}
**Deleting a language is permanent** and removes all content associated with it, including every translation that was written or generated for it. This cannot be undone.
{% endhint %}

## How end users get the right language

Userlane detects each user's language automatically. It checks a priority chain that starts with the application's own language setting and falls back through HTML tags, browser settings, and the default language configured in the portal. For the full priority list and the `lang` command that overrides detection, see [Userlane language detection](/developer-reference/userlane-language-detection.md).

When Userlane cannot match a user's language to any published language, a fallback rule decides what happens. The **Fallback solution** setting is set per content item (chapters, guides, tooltips, validators, and messages) and offers two options: show content in the default language, or hide the content so users without a matching language see nothing.

Showing the default language works when the content is understandable across language groups, or when something is better than nothing. Hiding content makes sense for region-specific material that would confuse users in other markets.

## Translate content automatically

Auto-translation generates translations from the default language into one or more target languages in a single action. Translations come from an AI-powered service, and someone fluent in the target language should review them before publishing.

Where you start auto-translation depends on the content type. For guides (including titles and all steps), tooltips, and validators, it runs from the Editor: select the target languages and start the process from the language controls on the content item. For announcements, a translation button is available in the message form when creating or editing the message. Chapters cannot be auto-translated.

Keep these points in mind:

1. The process can take several minutes for long guides translated into many languages. A guide with 15 steps across 20 languages may take up to ten minutes.
2. While auto-translation is running, the Editor is blocked. Other content cannot be edited until the process finishes.
3. The service may occasionally skip strings it cannot process. Those strings stay untranslated and need to be filled in by hand, so review the output after every run.

{% hint style="info" %}
**AI-powered translations.** No personally identifiable information (PII) is processed by the translation service, and no content is stored after the translation completes. For more on how Userlane's AI features handle data, see [AI features: what data is processed and where](/security-and-privacy/ai-features-what-data-is-processed-and-where.md).
{% endhint %}

## Translate content manually

You can also translate content by hand, either directly in the portal and Editor or offline through file export and import.

In the portal, you can translate announcements, welcome slide text, and default texts (the standard labels that appear in the Assistant[^3] and step boxes). Switch to the target language using the language dropdown, then edit the fields directly.

In the Editor, you translate guides, tooltips, and validators by switching to the target language in the language dropdown and editing each step, tooltip, or validator. The Editor opens in the last language you worked in. This helps when translating over several sessions, but check the dropdown before you start so you do not edit the wrong language.

### Export and import translations

For bulk translation work, export all texts to a CSV or XLSX file, translate offline, and import the file back. This is available under **Customize** > **Languages** > **Export/Import**. You can export texts for the entire application or for a single chapter or guide.

Keep the first two columns of the exported file unchanged, because they contain the identifiers Userlane uses to match content on import. Each language appears as a separate column, identified by its language code in the header row. If you only need to update specific languages, delete the columns for languages you are not changing before importing, so existing translations are not overwritten.

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FUxfearizeY5SPayZ5LQO%2Flanguage%20translation.png?alt=media&#x26;token=9155ee5a-bddb-470a-9dd5-e4b353773ff7" alt="The Export/Import option for translation files in the Languages settings"><figcaption><p>Exporting and importing translations.</p></figcaption></figure></div>

{% hint style="warning" %}
**Import affects the original language too.** Changes to any column in the export file, including the original language, are applied on import. Double-check the original-language column before importing if you only intend to update translations.
{% endhint %}

## Test translations

Before publishing a translation, create an audience[^4] that targets only yourself and apply it to the content you want to check. Log out of the portal, then open the application in a browser set to the target language. If the application controls its own language through an HTML attribute, change that setting instead. You can also force a language with the `lang` command, described in [Userlane language detection](/developer-reference/userlane-language-detection.md).

Check that all text appears translated, that nothing falls back to the default language unexpectedly, and that formatted content such as links and info boxes renders correctly.

## Supported language codes

Auto-translation and language matching support the IETF BCP 47 codes listed below. Use these codes as the language key when you create a language. If you need a code that is not listed, contact your Customer Value Manager.

{% hint style="info" %}
**Right-to-left languages.** Userlane delivers content in right-to-left languages such as Hebrew and Arabic. It does not adjust formatting for right-to-left text.
{% endhint %}

<details>

<summary>Full list of supported language codes</summary>

<table><thead><tr><th width="75.859375">Code</th><th>Language</th><th width="63.515625">Code</th><th>Language</th><th>Code</th><th>Language</th></tr></thead><tbody><tr><td>af</td><td>Afrikaans</td><td>en</td><td>English</td><td>mn</td><td>Mongolian</td></tr><tr><td>ak</td><td>Akan</td><td>eo</td><td>Esperanto</td><td>ne</td><td>Nepali</td></tr><tr><td>sq</td><td>Albanian</td><td>et</td><td>Estonian</td><td>no</td><td>Norwegian</td></tr><tr><td>am</td><td>Amharic</td><td>ee</td><td>Ewe</td><td>nb</td><td>Norwegian Bokmål</td></tr><tr><td>ar</td><td>Arabic</td><td>fo</td><td>Faroese</td><td>nn</td><td>Norwegian Nynorsk</td></tr><tr><td>hy</td><td>Armenian</td><td>fi</td><td>Finnish</td><td>or</td><td>Oriya</td></tr><tr><td>as</td><td>Assamese</td><td>fr</td><td>French</td><td>om</td><td>Oromo</td></tr><tr><td>az</td><td>Azerbaijani</td><td>gl</td><td>Galician</td><td>os</td><td>Ossetian</td></tr><tr><td>bm</td><td>Bambara</td><td>ka</td><td>Georgian</td><td>ps</td><td>Pushto</td></tr><tr><td>eu</td><td>Basque</td><td>de</td><td>German</td><td>fa</td><td>Persian</td></tr><tr><td>be</td><td>Belarusian</td><td>el</td><td>Modern Greek</td><td>pl</td><td>Polish</td></tr><tr><td>bn</td><td>Bengali</td><td>gu</td><td>Gujarati</td><td>pt</td><td>Portuguese</td></tr><tr><td>bs</td><td>Bosnian</td><td>ha</td><td>Hausa</td><td>pa</td><td>Panjabi</td></tr><tr><td>br</td><td>Breton</td><td>he</td><td>Hebrew</td><td>qu</td><td>Quechua</td></tr><tr><td>bg</td><td>Bulgarian</td><td>hi</td><td>Hindi</td><td>ro</td><td>Romanian</td></tr><tr><td>my</td><td>Burmese</td><td>hu</td><td>Hungarian</td><td>rm</td><td>Romansh</td></tr><tr><td>ca</td><td>Catalan</td><td>is</td><td>Icelandic</td><td>rn</td><td>Rundi</td></tr><tr><td>zh</td><td>Chinese</td><td>ig</td><td>Igbo</td><td>ru</td><td>Russian</td></tr><tr><td>kw</td><td>Cornish</td><td>id</td><td>Indonesian</td><td>sg</td><td>Sango</td></tr><tr><td>hr</td><td>Croatian</td><td>ga</td><td>Irish</td><td>gd</td><td>Scottish Gaelic</td></tr><tr><td>cs</td><td>Czech</td><td>it</td><td>Italian</td><td>sr</td><td>Serbian</td></tr><tr><td>da</td><td>Danish</td><td>ja</td><td>Japanese</td><td>sn</td><td>Shona</td></tr><tr><td>nl</td><td>Dutch</td><td>kl</td><td>Kalaallisut</td><td>si</td><td>Sinhala</td></tr><tr><td>dz</td><td>Dzongkha</td><td>kn</td><td>Kannada</td><td>sk</td><td>Slovak</td></tr><tr><td>en-us</td><td>English (US)</td><td>ks</td><td>Kashmiri</td><td>sl</td><td>Slovenian</td></tr><tr><td>en-gb</td><td>English (UK)</td><td>kk</td><td>Kazakh</td><td>so</td><td>Somali</td></tr><tr><td>es</td><td>Spanish</td><td>km</td><td>Central Khmer</td><td>sw</td><td>Swahili</td></tr><tr><td>sv</td><td>Swedish</td><td>ki</td><td>Kikuyu</td><td>ta</td><td>Tamil</td></tr><tr><td>tl</td><td>Tagalog</td><td>rw</td><td>Kinyarwanda</td><td>te</td><td>Telugu</td></tr><tr><td>th</td><td>Thai</td><td>ko</td><td>Korean</td><td>ti</td><td>Tigrinya</td></tr><tr><td>bo</td><td>Tibetan</td><td>ky</td><td>Kirghiz</td><td>to</td><td>Tonga</td></tr><tr><td>tr</td><td>Turkish</td><td>lo</td><td>Lao</td><td>uk</td><td>Ukrainian</td></tr><tr><td>ur</td><td>Urdu</td><td>lv</td><td>Latvian</td><td>uz</td><td>Uzbek</td></tr><tr><td>ug</td><td>Uighur</td><td>ln</td><td>Lingala</td><td>vi</td><td>Vietnamese</td></tr><tr><td>cy</td><td>Welsh</td><td>lt</td><td>Lithuanian</td><td>fy</td><td>Western Frisian</td></tr><tr><td>yi</td><td>Yiddish</td><td>lu</td><td>Luba-Katanga</td><td>yo</td><td>Yoruba</td></tr><tr><td>zu</td><td>Zulu</td><td>lb</td><td>Luxembourgish</td><td>mk</td><td>Macedonian</td></tr><tr><td>se</td><td>Northern Sami</td><td>mg</td><td>Malagasy</td><td>nd</td><td>North Ndebele</td></tr><tr><td>sh</td><td>Serbo-Croatian</td><td>ms</td><td>Malay</td><td>ii</td><td>Sichuan Yi</td></tr><tr><td>ml</td><td>Malayalam</td><td>mt</td><td>Maltese</td><td>mr</td><td>Marathi</td></tr><tr><td>gv</td><td>Manx</td><td></td><td></td><td></td><td></td></tr></tbody></table>

Regional variants (such as `en-us`, `en-gb`, `fr-ca`, `pt-br`, `zh-cn`, `zh-tw`, `de-at`, `de-ch`, `es-mx`, and `ar-sa`) are also supported. The full set runs to several hundred codes covering regional variants for each base language.

</details>

## Relevant articles

{% content-ref url="/pages/PuNlqTC5ezCbEiQV68xG" %}
[Userlane language detection](/developer-reference/userlane-language-detection.md)
{% endcontent-ref %}

{% content-ref url="/pages/VZqRoAJSjPm9ZGD2jNVG" %}
[Create and manage content](/assistance/content-operations/authoring/create-and-manage-content.md)
{% endcontent-ref %}

{% content-ref url="/pages/JKbJ88H839VzRksHakFJ" %}
[Announcements](/assistance/change-communication/announcements.md)
{% endcontent-ref %}

{% content-ref url="/pages/Zk1PSRimln0YLI1l2ZkI" %}
[Build an audience from attribute rules](/administration/audiences/build-an-audience-from-attribute-rules.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>What happens if I delete a language?</summary>

Deleting a language permanently removes all translations associated with it across every content type. This cannot be undone.

</details>

<details>

<summary>Can I auto-translate into all languages at once?</summary>

Yes. Select all target languages before starting the process. The translation runs for each language in sequence, so larger guides across many languages take longer.

</details>

<details>

<summary>Does auto-translation work for tooltips and validators?</summary>

Yes. Tooltips and validators are auto-translated from the Editor, the same way as guides. Chapters cannot be auto-translated.

</details>

<details>

<summary>What if a language code is not on the supported list?</summary>

Contact your Customer Value Manager. Userlane can add support for codes not currently listed.

</details>

<details>

<summary>How long does auto-translation take?</summary>

It depends on the length of the content and the number of target languages. A short guide translated into a few languages finishes in seconds. A guide with 15 steps translated into 20 languages can take up to ten minutes. The Editor is blocked while the process runs.

</details>

<details>

<summary>What does the fallback setting do?</summary>

It controls what an end user sees when their detected language does not match any published language: content in the default language, or no content at all.

</details>

[^1]: IETF BCP 47 is the standard for language tags used across the web and in software. A tag like `en-GB` or `de-DE` identifies both the language and the regional variant. Userlane uses these tags to match content to the end user's browser or system language.

[^2]: The Editor is the workspace where Userlane content is built, separate from the portal where content is targeted and analytics are viewed.

[^3]: The Assistant is the floating in-app panel that end users interact with. It provides access to guides, announcements, surveys, search, and connected knowledge sources.

[^4]: An audience is a reusable group of end users defined by attribute rules, used to control who sees which content.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/assistance/content-operations/languages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.