Internationalisation of Mu

A really useful and relatively simple way to contribute to Mu is to translate the user interface into a different language. The steps to do this are very simple and there exist plenty of tools to help you.

You can contribute in three ways:

  • Improve or extend an existing translation.
  • Create a completely new translation for a new locale.
  • Make a translation of Mu’s website (see the Developing Mu’s Website guide for how to do this).

In both cases you’ll be using assets found in the mu/locale directory.

Mu uses Python’s standard gettext based internationalization API so we can make use of standard tools to help translators, such as poedit.

Note

You may need to run make translate as part of this process. This, in turn, depends on the presence of the pygettext.py command on your system. The pygettext.py command should come installed as part of the Python language, but some operating systems don’t include it by default. For example, to install pygettext.py on Fedora you must make sure the python3-tools package is installed.

To manually change the locale Mu uses for translation strings, look in mu/__init__.py for the following lines of code at the start of the file:

# Configure locale and language
# Define where the translation assets are to be found.
localedir = os.path.join('mu', 'locale')
# Use the operating system's locale.
current_locale, encoding = locale.getdefaultlocale()
# Get the language code.
language_code = current_locale[:2]
# DEBUG/TRANSLATE: override the language code here (e.g. to Spanish).
# language_code = 'es'
gettext.translation('mu', localedir=localedir,
                    languages=[language_code], fallback=True).install()

As the comment suggests, temporarily update the language_code to the target language for translation, make your changes, as explained below, and re-run Mu to check your updates are correct and appropriate for your target locale.

Improve an Existing Translation

If you want to improve or extend an existing translation you should edit a file called mu.po for the target locale. Such files for existing translations are found in the mu/locale/<LOCALE>/LC_MESSAGES directory (remember to replace <LOCALE> with the value for the locale’s language / country code combination as specified by gettext convention).

Open the mu.po file in an editor or translation tool of your choice (we recommend poedit as a great solution for this). If you’re using a plain text editor, remember to make your changes to the message string (msgstr) not the message id (msgid).

Once you’ve saved and, most importantly, checked your translation strings appear as expected in Mu, commit your changes and create a pull request via GitHub. Alternatively, if you’re not a technical user, create a new issue in GitHub and attach your mu.po file along with details of the locale.

Create a New Translation

There are three steps to creating a new translation:

  1. [Optional] Use make translate to create an up-to-date messages.pot file.
  2. Use a tool like poedit to load the messages.pot file, select a language / locale and create appropriately translated messages.
  3. Save the resulting mu.po file into the mu/locale/<LOCALE>/LC_MESSAGES directory, replacing <LOCALE> with the value for the locale’s language / country code combination as specified by gettext convention.

Taking each in turn, you may (optionally) need to create an up-to-date specification of all the strings found within Mu that need translating. This is the messages.pot file and you simple need to issue the following command to regenerate it:

$ make translate

You’ll see some output ending with the message:

New messages.pot file created.
Remember to update the translation strings found in the locale directory.

To create a new translation you’ll need to use a tool such as poedit to load the messages.pot and configure output for a new locale. The resulting output is a mu.po file that needs to be saved in the mu/locale/<LOCALE>/LC_MESSAGES directory, replacing <LOCALE> with the value for the new locale’s language / country code combination as specified by gettext convention.

This process is illustrated below, with the cross-platform and open-source poedit tool.

Create New Translation

_images/po1.png

Select messages.pot

_images/po2.png

Specify the New Locale

_images/po3.png

At this point, simply use poedit to fill in the translated messages from the source messages.

Save mu.po when Finished

Note

Please make sure you check your translation is appropriate and correct for your target before submitting your work.

_images/po4.png