From BlenderWiki

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 /tools dir!

Translating

How it works

The /branches/<language>/ folders contain source files for translation system (<language> being an ISO language code, like es or zn_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>.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 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, as even if you can add a language in bf-translations project yourself, you’ll have to ask a developer to add it in Blender code, else it would be useless!

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, and a valid /trunk/po/tools/settings.py file. Then, just run:

$ cd where/you/put/trunk/po/tools
$ path/to/python3 ./update_branches.py <language>

(*nix users can skip the "path/to/python3" part, as scripts are executable.)

How to merge translations - translators

You might want to merge several po files together. To do so, you first have to choose a "dest" file, into which will be merged the translations and new messages of all others. Just run:

$ cd where/you/put/your/pos
$ path/to/python3 where/you/put/trunk/po/tools/merge_po.py dst.po src.po [src.po ...]

(*nix users can skip the "path/to/python3" part, as scripts are executable.)

Please read the help message of this script for more details (-h).

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.

About languages needing some po processing

This concerns at least, currently, arabic and persian.

The process is now standardized! Please follow those rules:

• The <language>.po file in /branches *must be the raw one* (i.e. non-processed).
• You *must* name your processing script <language>_to_utf.py (e.g. ar_to_utf.py), and it *must* be callable like this:

$ path/to/python3 <language>_to_utf.py raw.po processed.po

This way, the update_trunk.py (and import_po_from_branches.py) scripts will do the conversion automatically!

Administrating

These are advanced and/or /trunk-affecting operations, translators should avoid to use them.

Adding a new language

To do so, you *must* have both blender and its sources, and a valid /trunk/po/tools/settings.py file. Note that adding some code in Blender itself is also required!

For the bf-translation part, just run:

$ cd where/you/put/trunk/po/tools
$ path/to/python3 ./update_branches.py -a <language>

(*nix users can skip the "path/to/python3" part, as scripts are executable.)

Updating all po's under /branches

To do so, you *must* have both blender and its sources, and a valid /trunk/po/tools/settings.py file. Then, just run:

$ cd where/you/put/trunk/po/tools
$ path/to/python3 ./update_branches.py

(*nix users can skip the "path/to/python3" part, as scripts are executable.)

This will build new msg and pot files (in the temp dir, so they don’t even clutter your working dir), and update accordingly <language>.po's found under /branches/<language>, for all existing language.

Note you can restrict the update to a list of languages, simply by passing their ISO codes as command line arguments, see the help (-h).

Updating /trunk

To do so, you *must* have a valid /trunk/po/tools/settings.py file. Then, just run:

$ cd where/you/put/trunk/po/tools
$ path/to/python3 ./update_trunk.py

(*nix users can skip the "path/to/python3" part, as scripts are executable.)

This will:

• Remove all .po's from trunk.
• Check all /branches/<language>/<language>.po's, and import those valid and translated above 80% (by default, you can specify another threshold with -t option) into /trunk/po.
• Clean po's under /trunk/po (i.e. remove all commented messages in them).
• Compile all po's in /trunk/po to /trunk/locale/<language>/LC_MESSAGES/blender.mo.
• Clean translations that failed (i.e. remove from /trunk all mo's and po's that failed some way).

Tools

Here we quickly describes all scripts under /trunk/po/tools.

Note that all scripts also generates an help message when called with the "-h" option, please use this for more details.

Note for Windows users

You can find compiled builds of gettext in the lib folder under "binaries\gettext\" for both windows and win64.

In order to run the scripts you will need to replace the location of the GETTEXT_..._EXECUTABLE, in /trunk/po/tools/settings.py

For example:

-GETTEXT_XGETTEXT_EXECUTABLE = "xgettext"

+GETTEXT_XGETTEXT_EXECUTABLE = r"C:\Blender\lib\windows\binaries\gettext\xgettext.exe"

You will also have to specify python3's path, and perhaps others.

Settings - settings_template.py

Very important!

All scripts under /trunk/po/tools use a common setting source, settings.py

When freshly checked out, the /trunk/po/tools only contains a settings_template.py, which you should copy as settings.py, before editing that one.

For *nix users, most settings should be ok, except most probably BLENDER_EXEC and SOURCE_DIR.

Windows users will likely have to set the other executables' paths as well, as noted above.

Remember never to commit your settings.py file (else it would overwrite all others' on next update)! And to update it, when a new version of settings_template.py is committed.

Updating /branches tools

update_msg.py

This script runs _update_msg.py from inside Blender, to generate a trunk/po/messages.txt file (by default) containing all introspection-discovered messages (more than 98% of the messages!)

update_pot.py

This script first runs xgettext (over files listed in /trunk/po/POTFILES.in), to generate /trunk/po/blender.pot (by default), and then merges in all messages from /trunk/po/messages.txt.

update_po.py

This script runs msgmerge to update po's under /branches (by default) or under /trunk/po (-t, that option should never be used!), from /trunk/po/blender.pot.

update_branches.py

As we saw above, this script updates po's under /branches in one step. Under the hood, it obviously uses previous scripts!

Updating /trunk tools

import_po_from_branches.py

This script imports all .po that are advanced enough (default value is 80%, use -t for a different threshold) from /branches into /trunk/po.

update_mo.py

This script compiles po's under /trunk/po into mo's under /trunk/locale, creating directories if necessary.

update_trunk.py

As we saw above, this script updates po's and mo's under /trunk in one step. Under the hood, it obviously uses previous scripts!

Misc

check_po.py

This script can either run a quick test on po's (-m), make some raw stats (-s), or both. It can run over /branches po's (default), or /trunk/po po's (-t). It’s a report-only tool!

clean_po.py

This script removes all commented messages from /branches po's (default) or /trunk/po po's (-t).

merge_po.py

This script accepts two or more files as arguments, and merges into the first, dest file, the translations and new empty messages from all remaining files.

utils.py

This script gathers some commonly used functions, among which parser_messages, which reads and parse a po file.