Table of Contents


Kuma is localized with gettext. User-facing strings in the code or templates need to be marked for gettext localization.

We use Pontoon to provide an easy interface to localizing these files. Pontoon allows translators to use the web UI as well as download the PO files, use whatever tool the translator feels comfortable with and upload it back to Pontoon.


We do not accept pull requests for updating translated strings. Please use Pontoon instead.

See the Django documentation on Translations for how to make strings marked for translation in Python and templates.

Unless otherwise noted, run all the commands in this document inside the development environment.

For Docker on Linux, set UID in .env or enter the environment with docker-compose run --rm --user $(id -u) web bash, to ensure that created files are owned by your development user.

Getting the localizations

Localizations are found in this repository under the locale folder.

The gettext portable object (.po) files need to be compiled into the gettext machine object (.mo) files before translations will appear. This is done once during initial setup and provisioning, but will be out of date when the kuma locales are updated.

To refresh the translations, enter the development environment, then:

  1. Compile the .po files:

    make localecompile
  2. Update the static JavaScript translation catalogs:

    make compilejsi18n
  3. Collect the built files so they are served with requests:

    make collectstatic

Updating the localizations

When localizable strings are added, changed, or removed in the code, they need to be gathered into .po files for translation.


This work is done only during the preparation to push to production. You do not need to do this for your PR.

To update the localizations:

  1. Update kuma/settings/, and bump the version in PUENTE['VERSION'].

  2. Inside the development environment, extract and rebuild the translations:

    make localerefresh
  3. On the host system, review the changes to source English strings:

    git diff locale/templates/LC_MESSAGES
  4. Finally, commit the files:

    git add --all locale
    git commit

Adding a new locale (UI strings)

The process for getting a new locale on MDN is documented at Starting a new MDN localization. One step is to enable translation of the UI strings.

This example shows adding a Bulgarian (bg) locale. Change bg to the locale code of the language you are adding.

  1. Update the Localizations as above, so that your commit will be limited to the new locale.

  2. Add the locale to CANDIDATE_LANGUAGES in kuma/settings/

  3. Download the latest languages.json from and place it at kuma/settings/languages.json.

  4. Add the locale to translate_locales.html and the locale/ folder:

    make locale LOCALE=bg
  5. Generate the compiled files for all the locales, including the new one:

    make localerefresh
  6. Commit the changes to locale, jinja2/includes/translate_locales.html, and kuma/settings. The other locales should include a new string representing the new language.

When the change is merged to master, enable the language in Pontoon as well, and notify the language community to start UI translation.

Adding a New Locale (Page Translations)

Once the new translation community has completed the rest of the process for starting a new MDN localization, it is time to enable the language for page translations:

  1. Move the locale from CANDIDATE_LANGUAGES to MDN_LANGUAGES in kuma/settings/
  2. Restart the web server and verify that Django loads the new locale without errors by visiting the locale’s home page, for example http://localhost:8000/bg/.
  3. Commit the change to kuma/settings/

When the change is merged and deployed, inform the localization lead and the community that they can begin translating content.