<commit_before>============
Localization
============

Kuma is localized with `gettext <http://www.gnu.org/software/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.

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

.. _Pontoon: https://pontoon.mozilla.org/projects/mdn/
.. _Django documentation on Translations: https://docs.djangoproject.com/en/dev/topics/i18n/translation/

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 performed
during vagrant provisioning but if you need to update them at any time you can
compile the files via the following command within the vagrant environment::

    make localecompile

To update the static JavaScript translation catalogs, run the following django
management command::

    make compilejsi18n

The above command will build the JavaScript l10n files in the ``build/locale/``
folder. To collect these files for serving you must run the
``collectstatic`` command::

    make collectstatic

Updating the Localizations
==========================
#.  Run the following in the virtual machine (see :doc:`installation`)::

        make localerefresh

#.  Commit the files::

        git add --all locale
        git commit -m "MDN string update YYYY-MM-DD"

Adding a new Locale
===================
The examples shows adding a Bulgarian (bg) locale. Change ``bg`` to the locale
code of the language you are adding.

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

#. Add the locale to ``MDN_LANGUAGES`` in ``kuma/settings/common.py``

#. Add the locale to the ``locale/`` folder::

        make locale LOCALE=bg

#. Generate the compiled filed for all the locales, including the new one::

        make localerefresh

#. Restart the web server and verify that Django loads the new locale without
   errors by visiting the locale's home page, for example
   https://developer-local.allizom.org/bg/

#. Update the ``product_details_json.tar.gz`` files used by
   `our Travis install script`_::

        python manage.py update_product_details
        tar -czf etc/data/product_details_json.tar.gz ../product_details_json/

#. Commit the changes to ``locale/bg``, ``kuma/settings/common.py`` and
   ``etc/data/product_details_json.tar.gz``. Verify that the other locales are
   just timestamp updates before reverting them.

#. BONUS: Use the  `debug translation feature`_ of ``dennis-cmd`` to test a
   fake translation of the locale::

        cd locale<commit_msg>bug 1302459: Update docs for language updates<commit_after>============
Localization
============

Kuma is localized with `gettext <http://www.gnu.org/software/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.

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

.. _Pontoon: https://pontoon.mozilla.org/projects/mdn/
.. _Django documentation on Translations: https://docs.djangoproject.com/en/dev/topics/i18n/translation/

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 performed
during vagrant provisioning but if you need to update them at any time you can
compile the files via the following command within the vagrant environment::

    make localecompile

To update the static JavaScript translation catalogs, run the following django
management command::

    make compilejsi18n

The above command will build the JavaScript l10n files in the ``build/locale/``
folder. To collect these files for serving you must run the
``collectstatic`` command::

    make collectstatic

Updating the Localizations
==========================
#.  Run the following in the virtual machine (see :doc:`installation`)::

        make localerefresh

#.  Commit the files::

        git add --all locale
        git commit -m "MDN string update YYYY-MM-DD"

Adding a new Locale
===================
The examples shows adding a Bulgarian (bg) locale. Change ``bg`` to the locale
code of the language you are adding.

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

#. Add the locale to ``MDN_LANGUAGES`` in ``kuma/settings/common.py``

#. Download the latest ``languages.json`` from
   https://product-details.mozilla.org/1.0/languages.json
   and place it at ``kuma/settings/languages.json``.

#. Add the locale to the ``locale/`` folder::

        make locale LOCALE=bg

#. Generate the compiled filed for all the locales, including the new one::

        make localerefresh

#. Restart the web server and verify that Django loads the new locale without
   errors by visiting the locale's home page, for example
   https://developer-local.allizom.org/bg/

#. Commit the changes to ``locale/bg`` and ``kuma/settings``.
   Verify that the other locales are just timestamp updates before reverting
   them.

#. BONUS: Use the  `debug translation feature`_ of ``dennis-cmd`` to test a
   fake translation of the locale::

        cd locale
{'fraction_non_alphanumeric': 0.10012857602057217, 'fraction_numerical': 0.0033751205400192863, 'mean_word_length': 3.9467408585055646, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 7, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6398394', 'n_tokens_mistral': 1715, 'n_tokens_neox': 1602, 'n_words': 772}