Dev:Doc/Process/Translate Blender

Blender translation HOWTO

Here is a brief explanation of how translation works and how to update translation files. There is also a short presentation of all tools found in trunk/po/bl_i18n_utils dir (which is actually linked from Blender's source code repository)!

NOTE/WARNING I’m not sure all the command lines I give below are correct for this OS, and I couldn’t test the scripts on such system. Windows users, please tell me if there are any problems!

Note All this makes references to the bf-translations svn repository. Before being able to do anything, you must register on bf-translation project and request to join the team (just open a task for this)! This page also assumes you know how to use SVN, if not, please read that one.

Manage UI Translations Addon

Most of the maintenance work of i18n is now 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.

I18n addon preferences.

I18n Update Translation panel.

Translating

NOTE 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".

Pretty simple.

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).

An example of “edit translation” pop-up.

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 trunk/po/blender.pot file into branches/<language>/<language>.po new file.
• 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 /branches/<language>/ dir:

$ msgfmt --statistics <language>.po -o blender.mo

Then copy the produced blender.mo binary file under your .blender/locale/<language>/LC_MESSAGES/ dir.

Note 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 blender.mo!

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:

• The <language>.po file in 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 bl_i18n_utils module settings' IMPORT_LANGUAGE_RTL set. 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.

Administrating

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 release/scripts/modules/bl_i18n_utils/settings.py file, 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 /branches

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.

Updating /trunk

In the I18n Update Translation panel (bottom of Render buttons), select all languages, and hit Update Trunk.

This will:

• Check all /branches/<language>/<language>.po's, and import those valid and translated above 0% (by default, you can specify another threshold with in bl_i18n_utils' settings) into /trunk/po.
• Clean po's under /trunk/po (i.e. remove all commented messages in them), and run some consistency checks.
• Compile all po's in /trunk/po to /trunk/locale/<language>/LC_MESSAGES/blender.mo.

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 translations_tuple tuple).

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.

See the render_copy_settings addon as an example.

See Also

• The developer internationalization page.