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.

The strings are stored in a separate repository, https://github.com/mozilla-l10n/mdn-l10n


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.

Build the localizations

Localizations are found in this repository under the locale folder. This folder is a git submodule, linked to the mdn-l10n repository.

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, first update the submodule in your host system:

git submodule update --init --depth=10 locale

Next, 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

Update the localizations in Kuma

To get the latest localization from Pontoon users, you need to update the submodule.


This task is done by MDN staff or by automated tools during the push to production. You should not do this as part of a code-based Pull Request.

On the host system:

  1. Create a new branch from kuma master:

    git remote -v | grep origin  # Should be main kuma repo
    git fetch origin
    git checkout origin/master
    git checkout -b update-locales  # Pick your own name. Can be combined
                                    # with updating the kumascript submodule.
  2. Update the locale submodule to master:

    cd locale
    git fetch
    git checkout origin/master
    cd ..
  3. Commit the update:

    git commit locale -m "Updating localizations"
  4. Push to GitHub (your fork or main repository), and open a Pull Request.

It is possible to break deployments by adding a bad translation. The TravisCI job TOXENV=locales will test that the deployment should pass, and should pass before merging the PR.

Update the localizable strings in Pontoon

When localizable strings are added, changed, or removed in the code, they need to be gathered into .po files for translation. The TravisCI job TOXENV=locales attempts to detect when strings change by displaying the differences in locale/templates/LC_MESSAGES/django.pot, but only when a msgid changes.

When this happens, the strings need to be exported to the mdn-l10n repository so that they are available in Pontoon. If done incorrectly, then the work of localizers can be lost. This task is done by staff when preparing for deployment.

Add a new locale to Pontoon

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 will also enable the locale in development environments and on https://developer.allizom.org.


This task is done by MDN staff.

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

  1. Updating the localizable strings in Pontoon as above, so that your commit will be limited to the new locale.

  2. In kuma/settings/common.py, add the locale to ACCEPTED_LOCALES and CANDIDATE_LOCALES, and increase PUENTE['VERSION'].

  3. Download the latest languages.json from https://product-details.mozilla.org/1.0/languages.json 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. 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/.

  7. Commit the locale submodule and push to mdn-l10n, as described above in Updating the localizable strings in Pontoon. The other locales should include a new string representing the new language.

  8. (Optional) Generate migrations that includes the new locale:

    ./manage.py makemigrations users wiki --name update_locale
  9. Commit the changes to locale, jinja2/includes/translate_locales.html, and kuma/settings, and open a Pull Request.

  10. Enable the language in Pontoon, and notify the language community to start UI translations.

Enable a new locale on MDN

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:


This task is done by MDN staff.

  1. Remove the locale from CANDIDATE_LOCALES in kuma/settings/common.py. Ensure it remains in ACCEPTED_LOCALES.
  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/common.py and open a Pull Request.

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