Skip to main content

Creating interviews in multiple languages

Docassemble interviews can be translated into multiple languages. It includes handy features that load the translation at runtime, which means you do not need to maintain two separate versions of the interview to get the benefit of multiple languages.

The translation system is friendly for working with professional translators and amateur translators alike. It takes advantage of simple human-readable spreadsheets or text files.

The basics

Naming your language

In Docassemble, you reference the language you are using with a short name of your choice.

Most authors use 2-letter ISO 639-1 language codes to name their languages. If there is no appropriate 2-letter code, you should consider using ISO 639-3.

Some system phrases are already translated and keyed to the two-letter ISO 639-1 code. So it's a good idea to stick with this convention. But if you need to translate into a dialect and you can't find an official name, feel free to use one of your own invention. The official code is just a convention.

Switching languages

You can control the language of an interview by using the set_language() function. The name for the language you want to switch to is the only required parameter.

Docassemble checks the value of get_language() to decide what language to display system phrases and question text in. There is no built-in menu item that allows you to switch languages. You need to add a question or custom menu item that invokes set_language() at the appropriate time.

Incomplete translations

When a phrase has not been translated yet, the user will not get an error. Instead, Docassemble will show the default language.

Translation works off of an exact match. When you change the original language of a question, the translation will no longer be valid. Even changes to punctuation and white space will cause Docassemble to ignore the translation and show the page in its original language.

Despite this need for an exact match, the translation system is granular. Each field, option, question text, and subquestion text will be considered separate items to get translated. If some but not all phrases are translated, a partial translation will be shown.

What can be translated

All of the text in the Docassemble interface and interview can be translated.

Docassemble has separate systems for translating different kinds of interview text:

Kind of textDocassemble documentation page
Question textSpreadsheet or XLIFF file
System text (buttons, built-in menu items)words.yml
Code and metadata blocksAdd multiple blocks, with a language modifier
DocumentsLanguage modifier, also see Creating documents in languages other than English
Function outputLanguage-specific functions

Demo interview

Below is a small interview that demonstrates several translation features.

# This should always be the first line of the YAML. It needs
# to come before any text that will get translated
- phrases_es.xlsx # this spreadsheet has most of the interview phrases
navigation: True
language: en
- introduction: Introduction
- ending: Ending
# The `sections` block is one that doesn't appear in the
# translations spreadsheet. You need to use a language modifier
# instead
language: es
- introduction: Introducción
- ending: Conclusión
mandatory: True
code: |
set_language(language_choice) # This actually sets the language to the two-letter code below
question: |
What is your language?
- Language/lengua: language_choice
datatype: radio
- English: en
- Español: es
section: introduction
continue button field: intro
question: |
This is the first screen
subquestion: |
This is the subquestion area of the first screen.
- The first field: field1
- Select one or more: field2
datatype: checkboxes
- Label 1: value1
- Label 2: value2
- Label 3: value3
- Label 4: value4
section: ending
event: ending
question: |
All done
subquestion: |
When you use the comma_and_list() function, the word "and"
is translated so long as a words.yml is defined in the global configuration

The XLSX file phrases_es.xlsx has these contents:

docassemble.playground10language:language.ymlQuestion_10dbc292ca7541f124f4924e3f0dd9608denes"What is your language?
"¿Cuál es su idioma?
docassemble.playground10language:language.ymlQuestion_212a11e19cd150a312759299a692dc394aenes"This is the first screen
"Esta es la primera pantalla
docassemble.playground10language:language.ymlQuestion_221d8d0906aad3c23c4be70b376b8d02d8enes"This is the subquestion area of the first screen.
"Esta es el área de subpreguntas de la primera pantalla.
docassemble.playground10language:language.ymlQuestion_2375f398248f25e05bc99e157d7145c363enesThe first fieldel primer campo
docassemble.playground10language:language.ymlQuestion_24e055c0d5b54f36c2665d271fb86079fcenesSelect one or moreSeleccione uno o más
docassemble.playground10language:language.ymlQuestion_25eff63417104e8ebe57b3531054153264enesLabel 1Etiqueta 1
docassemble.playground10language:language.ymlQuestion_26f95d4806340464e46da38ed8a1ce45c6enesLabel 2Etiqueta 2
docassemble.playground10language:language.ymlQuestion_27a890dd1894c379ab876f8d2616ba5907enesLabel 3Etiqueta 3
docassemble.playground10language:language.ymlQuestion_28650857596fe374d17d7712d706f3864cenesLabel 4Etiqueta 4
docassemble.playground10language:language.ymlQuestion_31c46c51f9085b1460607798292bcf5232enes"All done
"Todo listo
docassemble.playground10language:language.ymlQuestion_320c5b0b5e1c20a9af00353e64f6d2a062enes"When you use the comma_and_list() function, the word "and" is translated so long as a words.yml is defined in the global configuration file. "Cuando usas la función coma_and_list(), la palabra ""y"" se traduce siempre que se defina un archivo words.yml en la configuración global archivo.

The XLSX file was created by visiting https://[myserver]/utilities and typing "docassemble.playground10language:language.yml" in the "Download an interview phrase translation file" box.

In the translation file, notice we left several lines that we do not want to translate blank.

The important columns are are the hash and tr_text columns. The translator can directly edit the tr_text column to add the translations that are needed. Any mako tags or other special syntax will be color-coded. Just let the translator know to ignore any text that is not black.

Read more

More complex multi-lingual interviews you can inspect