Localization

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

Note

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.

Note

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.

Note

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

To update the localizations, on the host system.:

  1. Start a new branch from Kuma master.

  2. Update the locale submodule to master:

    cd locale
    git fetch
    git checkout origin/master
    
  3. Update kuma/settings/common.py, and bump the version in PUENTE['VERSION'].

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

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

    cd locale
    git diff templates/LC_MESSAGES
    
  6. Commit the files in the locale submodule:

    git add --all .
    git commit
    

    For the commit message, use the PUENTE['VERSION'] in the commit subject, and summarize the string changes in the commit body, like:

    Update strings 2017.14
    
    * Updated survey on homepage
    
  7. Attempt to push to the mdn-l10n repository:

    git push
    

    If this fails, do not force with –force, or attempt to pull and create a merge commit. Someone has added a translation while you were working, and you need to start over to preserve their work:

    git fetch
    git reset --hard @{u}
    

    This resets your locale submodule to the new master. Start over on step 4 (make localerefresh).

  8. If the push to mdn-l10n is a success, commit your Kuma changes:

    cd ..
    git commit kuma/settings/common.py locale
    

    Push to GitHub (your fork or main repository), and open a Pull Request.

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://stage.mdn.moz.works.

Note

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 CANDIDATE_LANGUAGES, 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. Commit the changes to locale, jinja2/includes/translate_locales.html, and kuma/settings, and open a Pull Request.

  9. 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:

Note

This task is done by MDN staff.

  1. Move the locale from CANDIDATE_LANGUAGES to MDN_LANGUAGES in kuma/settings/common.py.
  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.