In this chapter, we will cover the following topics:
- Installing a language and configure user preferences
- Configuring language-related settings
- Translating texts through the web client user interface
- Exporting translation strings to a file
- Using gettext tools to ease translations
- Importing translation files into Odoo
Many of these actions can be done either from the web client user interface or from the command line. Whenever possible, we will show how to use either option.
Odoo is localization ready, meaning that it supports several languages and locale settings, such as date and number formats.
When first installed, only the default English language is available. To have other languages and locales available to the users, we need to install them.
We will need to have the Developer Mode activated. If it's not, activate it in the Odoo About dialog.
To install a new language in an Odoo instance, follow these steps:
- Select the menu option Settings | Translations | Load a Translation. On the resulting dialog, select the language to install from the list of available languages. If the website is installed, you will also be given the option to pick the websites where the language will be available.
- Now click on the Load button and the language will be installed.
- New languages can also be installed from the command line. The equivalent command for the preceding steps is:
$ ./odoo.py -d mydb --load-language=es_ES - To set the language used by a user, go to Settings | Users | Users and, in the Preferences tab of the user form, set the Language field value. While you are at it, you can use the opportunity to set the user's Timezone.
The users can also set these configurations themselves through the Preferences menu option, available when they click on the user name at the top right of the web client window.
The users can have their own language and timezone preferences. The former is used to translate the user interface text into the chosen language and apply local conventions for the float and monetary fields. The latter is used to display the datetime fields in the correct timezone.
Before a language is made available for the users to select, it must be installed with the Load a Translation feature. The list of installed languages can be seen with the Settings | Translations | Languages menu option.
Each Odoo addon module is responsible for providing its own translation resources that should be placed inside an i18n subdirectory. Each language's data should be in a .po file. Following our example, for the Spanish language, the translation data is loaded from the es_ES.po data file.
Odoo also supports the notion of base language. For example, if we have an es.po file for Spanish and an es_MX.po file for Mexican Spanish, then es.po is detected as the base language for es_MX.po. When the Mexican Spanish language is installed, both data files are loaded; first the one for the base language and then the specific language is installed. Thus, the specific language translation file only needs to contain the strings that are specific to the language variant, Mexican Spanish in our example.
The i18n subdirectory is also expected to have a <module_name>.pot file, providing a template for translations and containing all the translatable strings. The Export translation strings to a file recipe explains how to export the translatable strings to generate this file.
When an additional language is installed, the corresponding resources are loaded from all installed addon modules and stored in the Translated Terms model. Its data can be viewed (and edited) with the Settings | Translations | Application Terms | Translated Terms menu option.
Translation files for the installed languages are also loaded when a new addon module is installed or an existing addon module is upgraded.
Translation files can be reloaded without upgrading the addon modules by repeating the Load a Translation action. This can be used in case you have updated translation files and don't want to go through the trouble of upgrading the modules (and all their dependencies).
If the Overwrite Existing Terms checkbox is left empty, only new translated string is loaded. Thus, the changed translated string won't be loaded. Check the box if you want the already existing translations to also be loaded and overwrite the currently loaded translations.
The previous checkbox exists because we can do our specific translations editing Settings | Translations | Application Terms | Translated Terms, or using the Technical Translation shortcut option in the Debug menu. Translations added or modified this way won't be overwritten unless the language is reloaded with the Overwrite Existing Terms checkbox enabled.
It can be useful to know that the addon modules can also have an i18n_extra subdirectory with extra translations. The loading sequence for the translation files is: the .po files in the i18n subdirectory, first for the base language and then for the language; then the .po files in the i18n_extra subdirectory, first for the base language and then for the language. The last string translation loaded is the one that prevails.
The list of language codes can be seen in the source code; in the odoo/openerp/tools/misc.py file, look for the ALL_LANGUAGES variable. The GitHub link for the file is https://github.com/odoo/odoo/blob/9.0/openerp/tools/misc.py.