Blender UI Translation Guide
Here is a brief explanation of how translation works and how to update translation files.
Manage UI Translations Addon
Most of the maintenance work of translating is achieved through that official addon (found under the System category). Though it is not mandatory for translation-only tasks, it may be useful, and it is also needed for script authors that want to translate their own addons (please note that official addons are already handled by the main translation project).
The various features of this addon will be described in relevant sections below.
Gettext tools (msgfmt and msgmerge) are mandatory for most of those operations! If you are working with RTL languages (Arabic, Persian, Hebrew…), you’ll also need the C library FriBidi for your platform.
When you work on a translation, please only use the po’s under /branches directory. /trunk one is supposed to only contain valid (checked) po’s, only the maintainer is supposed to edit those!
How it works
The /branches/<language>/ folders contain source files for translation system (<language> being an ISO language code, like es or zh_CN). These source files have .po extension and a pretty simple syntax:
#: One or more lines of comments stating origins of the message. #, fuzzy [optional] see below # One or more lines of free, general comments msgid "some message id" msgstr "translation for this message"
In case msgid or msgstr are too long, they'll be split on several lines, like this:
msgid "" "A very very very very very very very very very very very very very very very" " very very very very dummy long message id!"
All this means that when the string "some message id" is used as operator name, tooltip, menu and so on, it'll be displayed on the screen as "translation for this message".
These source files are pre-compiled into /trunk/locale/<language>/LC_MESSAGES/blender.mo, which are binary files directly usable by the translation system.
How to edit translations - translators
It’s also pretty simple. If you can find string you want to translate in
/branches/<language>/<language>.po file as msgid, just write correct msgstr string for it. If msgid is marked as fuzzy, i.e.
#, fuzzy msgid "some message id" msgstr "translation for this message"
...it means translation used to exist for this message, but message was changed, so translation also have to be updated (it’s easier to make new translation based on previous translation).
When translation has been updated, remove line with
#, fuzzy and it’ll work.
Note: You can use a GUI to ease po files edition, like e.g. Poedit.
How to edit translations from Blender - translators
You can also, to some extent, translate Blender directly from within its interface, using the Manage UI Translations addon.
Once you have enabled it, you must first edit its preferences, so that at least Gettext 'msgfmt' executable and Translation Root paths are set to valid ones (the later is the path to your local checkout of the bf-translation repository).
Then, simply enable UI translation and select the language you want to work on (note that once a language is selected, it will be the translated one, even when UI translation is disabled), and right-click over any UI item, Edit Translation option will pop-up a box gathering all messages that could be found attached to that button and/or the underlying RNA data.
Once again, do not expect to be able to translate everything with that system, many messages are simply not reachable this way!
Note in the picture to the right that the popup features you several data:
- The PO file edited with some basic statistics.
- The RNA path of the property, structure or operator edited.
- The RNA context used to translate the labels.
- All labels that could be gathered (usually, RNA one, and optionally button-level overridden one, e.g. here the operator’s label is “Render”, but as that button uses it to render animations, it has overridden it with “Animation”).
- All tips that could be gathered (in most cases, only the RNA one!).
For each of those messages, you have the original one, a text field to edit the translation, and a toggle button to mark it as fuzzy.
Once you have finished your edits, you can simply click on the OK button to validate and close the popup, but beware: your changes won’t be saved in the PO file! So regularly, you’ll toggle the Save To PO File option, so that your edits get written into the relevant file.
You may also wish to see your edits reflected in the UI ? Just enable the Rebuild MO File toggle to do so. But beware, this will create a new MO in your user Blender-data directory, which will have as side effect that all default, official translations will be no more used by Blender. To revert to default situation, just enable Erase Local MO Files instead.
How to add translations - translators
If you have not yet your languages under
/branches, you should request (e.g. on the ML) an administrator to add it.
Meanwhile, you can start to work, following those steps:
- Copy/paste the
- Start translating this file!
Do not forget to commit your changes in the svn repo!
When you want to see your work in action in Blender, if your languages has not been added yet to Blender by an administrator, you can edit the file
datafiles/locale/languages found into your blender configuration directory, and add in it a line for your language. The format of this file is described in it, just take care to use a (temp!) ID above max one currently in use.
Then, generate and test your mo file, as explained here.
How to update translations - advanced translators
All po's under
branches/ should be updated something like once a week by an administrator.
However, you can do it yourself for your language, if needed.
To do so, you must have both blender and its sources, have enabled the i18n addon, and valid values for its preferences' Source Root and Translation Root.
Then, in the I18n Update Translation panel (bottom of Render buttons), select the language(s) you want to update, and hit Update Branches.
How to merge translations - translators
Simply use msgcat for now (
msgcat -o output_file.po input_file1.po input_file2.po …, see its help for more info).
How to test your translations - translators
To test your translations, simply run, from your
$ msgfmt --statistics <language>.po -o blender.mo
Then copy the produced blender.mo binary file under your
Some po editors (like poEdit) generate by default a .mo file when saving. In this case, just copy this file into the relevant dir as stated above, and rename it to
About languages needing some po RTL processing
This concerns at least, currently, arabic, persian and hebrew.
The process is now standardized! Please follow those rules:
branches/must be the raw one (i.e. non-processed).
- The language must be specified as RTL by adding its uid (ISO code) to the
IMPORT_LANGUAGE_RTLset. This is a dev task, please ask e.g. to i18n maintainer to do so, if needed.
This way, i18n addon's tools will do the conversion automatically (using underlying fribidi library) when needed.
Issues with the text
Sometimes you may see some text in the UI, but no matching message exists in the translation files. This probably means that the developers forgot to make them translatable.
Another issue is that of contexts. The translations use contexts, to disambiguate between different meanings of a single word. By default no context is used, so sometimes it’s impossible to translate one message without messing up another.
And sometimes, a message is just wrong, has a typo, or is not very clear, even in English.
If any such issue arises, please notify developers in this task.
About translating the name "Blender"
Some usages of the program name "Blender" are marked as translatable, like for window titles. In almost all cases, you should not translate the string "Blender". And never completely replace it.
Translating the string should only be considered if the latin text of "Blender" cannot be used as a noun by your target audience. For an example of this, consider that most English users could not use "トヨタ" as a noun, but instead use "Toyota". So if your language characters are ideographic, the phonemes in your language do not support the sounds in "Blender" well or make it rude or weird, or otherwise render "Blender" as a noun unusable on its own, consider appending to the string. For example if "Blender" would not be pronounceable, consider translating the string so that it includes both "Blender " and a short transliteration of the name sounds in your script. If your script is ideographic, you could similarly consider appending translation characters after "Blender ". Ideographic translation of Blender would indicate what it is and what it does, and would never have anything to do with the kitchen appliance of the same name.
An example of this can be seen on the signs for McDonald's restaurants in China. These generally show "McDonald's 麦当劳", a transliteration of the English name as 'Maidanglao', though literally meaning 'wheat serves labor.' Although they have recently rebranded to 'Jingongmen' (金拱门), which translates to 'Golden Arches.'
These are advanced and/or
/trunk-affecting operations, translators should avoid to use them. We assume you have valid blender sources, blender build (should be as much similar to official ones as possible), and bf-translations repository, and that i18n addon is enabled and its settings are valid.
Adding a new language
First of all, edit the
LANGUAGES tuple, to add this new language. Then rebuild/reinstall Blender, the new language should appear in the menus now. Simply update
branches/ with the new language selected to generate a new void PO file for it.
Updating all PO's under
In the I18n Update Translation panel (bottom of Render buttons), select all languages, and hit Update Branches (keep Skip POT deselected!).
Note you can restrict the update to a list of languages, simply deselecting unwanted ones.
You should also typically run Clean up Branches to remove existing invalid entries, commented ones, etc.
In the I18n Update Translation panel (bottom of Render buttons), select all languages, and hit Update Trunk.
- Check all
/branches/<language>/<language>.po's, and import those valid and translated above 0% (by default, you can specify another threshold within
bl_i18n_utils' settings) into
- Clean po's under
/trunk/po(i.e. remove all commented messages in them), and run some consistency checks.
- Compile all po's in
- Copy and strip to their bare minimal all po's into the git repository directory.
Translating non-official addons
Translation of those addons is primarily handled through a Python dict named
translations_dict, a mapping of mappings, with language uids (ISO codes) as higher-level keys, and messages → translations mappings as values. This dict must be registered by a call to
bpy.app.translations.register() and unregistered by a call to
bpy.app.translations.unregister(), exactly as the addon itself.
Typically, this dict is generated from a tuple named
translations_tuple, which is a tuple of tuples
((msgctxt, msgid), (sources, gen_comments), (lang, translation, (is_fuzzy, comments)), ...).
Now, I don’t expect much addon author to be happy at the idea of writing and maintaining such code, keep track of changes in the UI messages, etc. So i18n addon is here again to help with these tasks.
In the I18n Update Translation panel (bottom of Render buttons), select the language(s) you want to work on, and choose between the options under the Addons: operators – you will always be ask to select the affected addon through a search box pop-up:
- Refresh I18n Data…
- Extract the UI messages specific to the selected addon, and update (or create) relevant py code (the
- Export PO…
- Export current py code into PO files for the selected languages (and optionally generate a POT file too).
- Import PO…
- Import all PO's under given directory, and update the selected addon's py code accordingly.
Please note that:
- If a message is already present in main Blender translation, it won’t be added to the addon’s ones, so you will have to use a custom context if you absolutely need a custom translation.
- The tools use some “markup” to locate the generated code, so you may move that block of code anywhere you like.
render_copy_settings addon as an example.
Quickly toggle the UI language
It’s possible to create a keyboard shortcut to toggle the UI between English and your language, in order to check that the translation matches the original text, or to reload it by toggling twice.
- Go to the User Preferences, Keymap, Window, Add New
- Unfold the new keymap by clicking the arrow to the left, and replace
- In the Context Attributes field, enter
- In the Value fields, enter
DEFAULTand your language code (for instance,
pt_BR; you can get the code in the Translation preferences by hovering the Language field)
- Assign the shortcut to a free combination, for instance Ctrl + Alt + Shift + L.