Internationalizing Mercurial

This page will describe how you can help internationalize Mercurial by translating it into your language of choice. Mercurial uses the standard i18n [http://www.gnu.org/software/gettext/ Gettext] infrastructure, and we will only give a quick introduction to it here. Please take a look at the Gettext manual if you are unfamiliar with translating software.

Starting a New Translation

If you find that Mercurial is not yet translated into your favorite language, then you can start one. First contact the development MailingList to see if an effort is already underway.

Translations are stored as xx.po and xx_yy.po files in the i18n/ directory. The xx corresponds to the language code of the translation and the yy is the optional country code. Find your language code in the [http://www.gnu.org/software/gettext/manual/html_node/Usual-Language-Codes.html ISO 639-1 list] and, if needed, your country code in [http://www.gnu.org/software/gettext/manual/html_node/Country-Codes.html ISO 3166 list].

To create a new translation you first create a i18n/hg.pot file. This is can be done with the Makefile:

% make update-pot

The Makefile requires the pygettext and msgmerge programs. If you do not have pygettext installed you can find it [http://svn.python.org/view/python/trunk/Tools/i18n/ on the Python SVN server].

You create your translation from the hg.pot file. You can use the msginit program to start a new translation or you can copy the hg.pot file to the correct xx.po name.

Now edit the xx.po file with your favorite PO editor, such as [http://www.poedit.net/ Poedit] or Emacs. You can also simply edit the xx.po file with a text editor (such as WordPad), but you must then be careful to keep the formatting.

• Please note that the hg.pot file contains some strings which need not be translated. These strings document internal functions in the extensions and are unfortunately mixed with regular strings. We plan to make a more accurate extraction tool in the future. For now we suggest that translators keep to the strings they see in the output.

To actually use the translation you need to compile the xx.po file into a xx.mo If you have the msgfmt program installed you can do the compilation like this:

% python setup.py build_mo

Alternatively, you can let Poedit do the compilation or you can use the msgfmt.py script found alongside the pygettext.py script. The resulting file should be called hg.mo and must be saved as

locale/xx/LC_MESSAGES/hg.mo

Using setup.py does this for you, if you compiled the xx.po file manually you have to create the directory structure yourself.

Now ensure that your LANGUAGE environment variable is set to 'xx'. In a shell from the Bash-family you do this by:

% export LANGUAGE=xx

Then run hg to see if your translations are picked up.

Updating a Translation

When changes are made to the Mercurial source, new strings will appear that must be translated. Updating an old translation to take these strings into account is easy: regenerate the hg.pot file as above and use the msgmerge program to merge new strings into the translation:

msgmerge --no-location --update i18n/xx.po i18n/hg.pot

Antother way is to call make with the po-file

make i18n/xx.po

This combines the regeneration of hg.pot and  msgmerge.

Then translate the new strings, make the xx.mo file and enjoy.

If you prefer to have the location information present while working on the translation, then leave out the --no-location flag above. The location info from hg.pot will then be merged into the xx.po file and you will be able to quickly jump to the source fo a given translation.

To avoid creating excessive diffs you must strip out this information before committing your translation:

msgcat --no-location -o xx.po xx.po

You should always use hg diff to check that your patch contains only the necessary changes. When you are happy with your translation, please use the PatchbombExtension to send it to the MailingList.

Formatting

The translations of command help texts should be word-wrapped at 70 characters. Please follow this pattern:

short description, starting with lowercase

    Larger description of the command. Each paragraph should be
    word-wrapped at 70 characters and indented with 4 spaces.

    Paragraphs are separated by a single empty line. Use a single
    space between sentences.

Tips

In order to translate the most important strings first, you may want to use the [http://bitbucket.org/mg/hg-i18nstat/ i18nstat extension]. This extension will log each string translated and count the number of times an untranslated string is used.

You simply have to enable the extension and then use Mercurial like normal. Use hg i18nstat to dump the accumulated statistics. When you translate one of the missing strings, it will disappear from the statistics the next time it is used (the extension wont notice that it is translated unless the string is used).

Existing Translations

Translations distributed with Mercurial:

• Danish (MartinGeisler)

• German (TobiasBell) -- Development takes place at http://bitbucket.org/tobidope/mercurial-german-translation/

• Italian (StefanoTortarolo)

• Japanese (KatsunoriFujiwara) -- Development takes place at http://bitbucket.org/foozy/mercurial-translation-ja/

• Simplified Chinese (DongshengSong)

Translations not yet distributed with Mercurial:

• French (RomainPelisse) -- patch queue: http://bitbucket.org/rpelisse/hgbook-fr/ , dedicated mailing list : hgfr-subscribe@flibuste.net (obvioulsy, the mailing list is in French )

• Greek (GiorgosKeramidas) -- patch queue: http://bitbucket.org/keramida/hg-i18n-el/

• (Work in progress) Traditional Chinese (Chia-Huan Wu a.k.a. Willie) -- patch queue: http://bitbucket.org/willie/hg-cht-translation/

• add a link to your translation here!

Please contact the person listed above if you would like to help with a particular language. If you want to start a new translation, then add the language and your name to the list and go ahead.