> For the complete documentation index, see [llms.txt](https://docs.talentmap.com/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talentmap.com/knowledge-base/survey-design-and-deployment/creating-surveys-quick-start/adding-translations-to-a-survey.md).
# Adding Translations to a Survey
Translations let respondents complete a survey in their preferred language. The workflow is export, translate in Excel, then import. Once translations are uploaded, respondents see a language picker on the survey page, and Compass auto-detects their browser language to set the default.
***
#### What translations do
A translated survey shows the same questions, response options, instructions, and system messages in the language each respondent chooses. Translations are display-only. All responses map back to the source question, so benchmark calculations and reporting are unaffected by which language a respondent used.
You can add as many languages as you need to a single survey. Each language is added by appending a column to the translation Excel file.
***
#### When to use translations
* Bilingual or multilingual workforces (e.g., English and French in a Canadian organization).
* Organizations with non-English-speaking participants who need a localized survey experience.
* Surveys distributed across multiple regions where consistent translation is required.
* Public sector organizations with statutory bilingualism requirements.
***
#### How translations work
The translation workflow is three steps:
1. **Export** the translation file from your survey. Compass generates an Excel file containing every translatable element.
2. **Translate** in Excel. Each language is a column. The first row is the column header (the language code). Subsequent rows are the translations.
3. **Import** the completed file. Compass validates each row and surfaces any errors before the translation is applied.
> **Editing translations.** To change an existing translation, export the current file, edit it, and re-import. Direct in-platform editing is not yet available.
***
#### Step 1: Export the translation file
1. Open the survey from the **Surveys** page.
2. Click **Design Survey** in the left navigation.
3. Click the **TRANSLATION** dropdown in the top-right toolbar.
4. Click **EXPORT**.
Compass downloads an Excel file named `translations_survey_[id].xlsx`. The file contains:
* A `Type` column identifying the kind of element (page, question, response option, system message, etc.).
* A `Key` column with the unique identifier for each element. Do not edit this column.
* A `default` column with the source text, typically in English.
* One column per language already in the survey, identified by language code in the header row.
If the survey has no translations yet, the file will only have `Type`, `Key`, and `default` columns. Add a new column for each language you want to support.
> **Do not edit the Type or Key columns.** These columns identify each row to Compass on import. Changing them will cause the import to fail or apply translations incorrectly.
***
#### Step 2: Add your translations in Excel
For each language you want to add:
1. Add a new column to the right of the `default` column.
2. Set the column header to the language code from the reference table below.
3. Translate each row in the `default` column into the target language.
4. For rows where the source text contains HTML (rich-text formatting on page descriptions, instructions, or HTML blocks), translate the visible text only. Leave the HTML tags untouched.
**Example:**
| Type | Key | default | fr |
| ------ | ------- | --------------------- | --------------------------- |
| title | | TalentMap Exit Survey | Sondage de départ TalentMap |
| page | uuid... | Welcome to the survey | Bienvenue au sondage |
| choice | uuid... | Strongly Agree | Tout à fait d'accord |
> **Best practice for rich text.** When the source text includes HTML (e.g., `Note:`), translate only the words, not the markup. Replace `Note: Immediate Leader...` with `Remarque : Le supérieur immédiat...`.
***
#### Step 3: Import the file
1. Click the **TRANSLATION** dropdown in the top-right toolbar.
2. Click **IMPORT**.
3. Select your completed Excel file.
Compass validates the file before applying changes. If the file has errors, the import dialog lists each problem with the row and column. Fix the errors in Excel and re-import.
***
#### How respondents see translations
Once translations are imported, the survey page shows a globe icon. Respondents click it to switch the survey display into their preferred language.
**Browser auto-detection.** When a respondent opens the survey, Compass reads their browser language preference and sets the survey to the matching language if it has been uploaded. If no match is found, the survey defaults to the source language (typically English).
**Manual language switch.** Respondents can change their language at any point during the survey by clicking the globe icon. The choice persists for the duration of their session.
***
#### Previewing translations
Before launching the survey, preview each translation to catch formatting issues, missing translations, and rich-text rendering problems.
1. In Design Survey, click the **Preview** tab.
2. Use the language picker on the preview page to switch between uploaded languages.
3. Walk through every page to confirm questions, response options, and rich-text blocks render correctly.
> **Common preview check.** Confirm rich-text formatting (bold, headings, links) survived the translation. If a translator removed or broke an HTML tag, the affected text may render plain or break the page layout.
***
#### Editing existing translations
To update a translation that has already been imported:
1. Click **TRANSLATION > EXPORT** to download the current file.
2. Edit the cells you want to change in Excel.
3. Click **TRANSLATION > IMPORT** to upload the updated file.
Compass replaces the existing translations with the contents of the imported file.
> **Re-importing replaces, not appends.** When you re-import, the imported file becomes the authoritative source for every language in the file. Always export the current file as your starting point so you don't drop translations.
***
#### Supported language codes
Use the language code (left column) as your Excel column header. Codes are based on ISO 639-1 with regional variants where supported.
| Language | Code | Native name |
| ------------------- | ----- | -------------------- |
| Arabic | ar | العربية |
| Basque | eu | Euskara |
| Bulgarian | bg | Български |
| Burmese | mm | မြန်မာ |
| Catalan | ca | Català |
| Croatian | hr | Hrvatski |
| Czech | cs | Čeština |
| Danish | da | Dansk |
| Dutch | nl | Nederlands |
| English | en | English |
| Estonian | et | Eesti |
| Filipino | fil | Filipino |
| Finnish | fi | Suomi |
| Flemish | nl-BE | Vlaams |
| French | fr | Français |
| Georgian | ka | ქართული |
| German | de | Deutsch |
| Greek | gr | Ελληνικά |
| Haitian Creole | ht | Kreyòl Ayisyen |
| Hebrew | he | עברית |
| Hindi | hi | हिन्दी |
| Hungarian | hu | Magyar |
| Icelandic | is | Íslenska |
| Indonesian | id | Bahasa Indonesia |
| Italian | it | Italiano |
| Japanese | ja | 日本語 |
| Kazakh | kk | Қазақ |
| Khmer | km | ខ្មែរ |
| Korean | ko | 한국어 |
| Latvian | lv | Latviešu |
| Lithuanian | lt | Lietuvių |
| Macedonian | mk | Македонски |
| Malay | ms | Bahasa Melayu |
| Norwegian | no | Norsk |
| Persian | fa | فارسی |
| Polish | pl | Polski |
| Portuguese | pt | Português |
| Portuguese (Brazil) | pt-br | Português Brasileiro |
| Romanian | ro | Română |
| Russian | ru | Русский |
| Serbian | rs | Српски |
| Simplified Chinese | zh-cn | 简体中文 |
| Slovak | sk | Slovenčina |
| Slovenian | sl | Slovenščina |
| Spanish | es | Español |
| Swahili | sw | Kiswahili |
| Swedish | sv | Svenska |
| Tajik | tg | Тоҷикӣ |
| Telugu | tel | తెలుగు |
| Thai | th | ไทย |
| Traditional Chinese | zh-tw | 繁體中文 |
| Turkish | tr | Türkçe |
| Ukrainian | uk | Українська |
| Urdu | ur | اردو |
| Vietnamese | vi | Tiếng Việt |
| Welsh | cy | Cymraeg |
***
#### Permissions
| Role | Can manage translations |
| ---------------------------- | ----------------------- |
| HR Admin / Org Admin | No |
| Survey Creator | Yes |
| Project Manager | Yes |
| Report Viewer | No |
| TalentMap Admin / Consultant | Yes |
***
#### FAQ
**How many languages can I add to one survey?**
There is no fixed limit. Each language is a column in the Excel import file.
**What happens if a translation is missing for a question?**
Compass falls back to the source language (typically English) for any question or response option that is not translated.
**Can I add translations to a survey that is already live?**
Yes. New translations apply immediately. Respondents who haven't submitted yet can switch to the new language. Submitted responses remain attributed to the language used at submission.
**Does the language picker show every language I uploaded?**
Yes. The picker lists every language that has at least one translated row in the imported file. Languages with all-blank columns are skipped.
**How does browser auto-detection work?**
When a respondent opens the survey link, Compass reads the language preference from their browser and matches it to the uploaded translations. If their browser is set to French and the survey has French uploaded, they see the French version. If no match, they see the source language. They can override the choice with the globe icon at any time.
**Do translations affect benchmarking?**
No. Translations are display-only. All responses map back to the source question, so benchmark calculations are unaffected.
**Can translators work directly in Compass?**
Not yet. Translators work in the Excel file you export. To onboard a translator: export the file, send it to them, receive the completed file, then import it.
**What format does the import expect?**
Excel `.xlsx`. The file structure is set by Compass on export, so the simplest workflow is to always start from a fresh export.
***
#### Troubleshooting
| Issue | Solution |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Globe icon not showing on the survey page | Confirm at least one language has been imported and the survey has been saved since import. |
| Import fails with row errors | Open the file, check for blank source-text cells, missing language headers, or rows where the `Key` column was changed. Fix and re-import. |
| Translated text appears in the wrong place | Confirm the `Key` column was not edited. Compass uses Key to match each row to a survey element. |
| Language not appearing in the picker | Re-export the current translations, confirm the language column is present and has translated text, and re-import if missing. |
| Special characters showing as question marks | Save the Excel file with UTF-8 encoding before importing. |
| Rich-text formatting broken in translation | Re-translate the row keeping all HTML tags intact. Translate the visible text only, not the markup. |
| Browser auto-detect not working | Confirm the respondent's browser language is set correctly and matches an uploaded language code (e.g., browser set to `fr-CA` matches uploaded `fr`). |
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.talentmap.com/knowledge-base/survey-design-and-deployment/creating-surveys-quick-start/adding-translations-to-a-survey.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.