docassemble allows you to write a single interview that asks questions differently depending on the user’s language and locale. It also allows Unicode to be used in user-facing text, user input, and documents. With these features, docassemble should be fully usable in languages other than English.
The value of
locale must be a locale name without the language
prefix, such as
DE.utf8. Any locale you use must be
installed on your system. (See the
other os locales configuration
Within interviews, the functions
set_locale() will change the active language, locale, and dialect.
(The dialect is relevant only for the text-to-speech feature, which is
controlled by the special variable
If you write functions that need to know the current language or
locale, use the
get_locale() function from
docassemble.base.util module. Also note that there is a
get_dialect() for retrieving the dialect.
- When docassemble looks for a
codeblock that defines a variable, it first tries
codeblocks for which the
languagemodifier is set to the active language (either explicitly or by operation of the
default language). If docassemble does not find any such
codeblocks, it looks for ones that do not have
languagemodifier set. This means that if your interview only uses one language, you do not need to worry about setting the
languagemodifier. If you want the interview to be available in two languages, then you simply need to make sure that each question is in your interview two times, in the two different languages.
- Built-in words like “Continue” for a continue button, or “Login” for
the login link, will be translated into the active language.
Whenever docassemble prints such a word or phrase, it calls the
word()function from the
word('Login')will look up the word
Loginin a translation table. If the
word()function finds the word
Loginin the translation table for the active language, it will return the translated value. If it does not find a translation, it will return
Login. For more information about how
word()works, see functions. For information on how to define translations for a server, see the
wordsdirective in the configuration.
- Some functions have language-specific responses, such as
docassemble.base.utilmodule, which returns today’s date in a readable format such as “October 31, 2015” (for language
en) or “31 octobre 2015” (for language
- When docassemble highlights
termsin a question (see initial blocks), it will only highlight words specified in
termsblocks for which the
languageof the term matches the language of the question. Or, if the question does not have the
languagemodifier set, docassemble will look for a
termsblock that does not have
- When docassemble displays
interview helptext, it will only display the content of
interview helpblocks for which the
languagemodifier is the same as the language of the question. Or, if the question does not have the
languagemodifier set, docassemble will look for an
interview helpblock that does not have the
Best practices for single-language interviews
If your interview only works in one language, do not set the
language modifier for any blocks, do not use
and do not call
simply make sure that the default
locale in the
configuration are set to the correct values.
Best practices for multi-language interviews
If you use the
language modifier or the
default language, you will need to have
initial code that calls
set_language(). docassemble does not remember the active
language from one screen to the next, but the
initial code will
make sure that it is always set to the correct value.
If you are writing an interview that offers multiple language options, you may want to break out your interview into different files:
code.yml- for language-independent initial blocks, interview logic, questions, and code blocks.
en.yml- for English-language
default language: enas the first line.
es.yml- for Spanish-language
default language: esas the first line.
interview.yml- the main file, which simply
includes the above three files.
Below is an example of a multi-language interview that asks the user
for a language, then asks for a number, then makes a statement about
the number. The interview is split into the four files listed above,
and all files reside in a folder called
bestnumber within the
The contents of
The contents of
The contents of
Finally, the contents of
Creating documents in languages other than English
The documents feature, which allows RTF and PDF documents to be
created from Markdown text with Mako templating, supports
languages other than English to the extent that RTF, Pandoc, and
LaTeX do. LaTeX has support for internationalization, and the
default LaTeX template will load either the polyglossia package or
the babel package, depending on what is available. The language
used by LaTeX can be set using the
mainlang in the
attachment specification. For some languages, you
may need to write your own templates in order to enable fonts that
support your language.