CONTRIBUTE.rst

contribute to l18n

If you are reading this, you're interested in contributing to l18n. Great news!

2 main ways to contribute:

• add features or fix bugs
• add languages

This document will cover mainly the 2nd way. For the 1st way, that's easy: just dive into the code, the tests, and create a pull request. You may want to read the tests/_README.rst file.

Adding a language

Adding a language to l18n is relatively easy but requires a little bit of work for one simple reason: the CLDR provides translation for many timezones defined in pytz (which come from the Olson database), but not all of them. Indeed, there are a few of them that are missing or not very accurate, and that require a little bit of manual work.

Step 0: how the translation files generation works

The translation files, as well as a __maps.py module, are generated by a dedicated python package, which is located in the maker directory of this repository. It has one entry point: build.

Calling build does 3 things:

• it fetches the relevant pages from the CLDR website and extracts the needed translations
• it retrieves missing or more precise translations from locale files in the overrides directory
• it generates the translation files and the __maps module.

After the build, a distribution can be created and uploaded to pypi.

Step 1: adding the language to the maker's settings

To make l18n_maker fetch the translations for a language from the CLDR website, simply add the language to l18n_maker.settings.LOCALES tuple.

I told you it was simple ...

Step 2: adding a translations overrides file

The timezones for which no translation can be found in the CLDR are listed in the file overrides/root. This file provides the mappings for fallback translations. Some of the entries may not change in your language, some are likely to be different.

You need to:

• copy overrides/root to overrides/your_language
• remove each line of overrides/your_language for which the name in your language is the same compared to the fallback one
• edit each line of overrides/your_language for which the name in your language is different from the fallback one. It may require a few Google searches!

You can have a look at the existing files for examples in other languages.

Step 4: building the translation files

To build the translation files, you need to go into the package's main directory and run the following commands:

python bootstrap.py       # this creates the 'bin/buildout' script
bin/buildout parts=build  # this creates the 'bin/build' script
bin/build                 # this generates the files

You can have a look at the output, which will notify you if:

• A translation was not found for a timezone or territory: this is an issue that must be reported and fixed asap.
• A translation was found both in the CLDR and in an overrides/* file: this is normal in case a CLDR translation was not satisfying (e.g for the 'Pacific/Easter' timezone that is translated to 'Easter' while it should be 'Easter Island') and needed to be overriden.
• A translation was found in an overrides/* file but is not or no longer in pytz.all_timezones. This translation override can be safely removed.

Step 5: checking that everything is ok

You may want to open the generated locale/your_language/LC_MESSAGES/l18n.po with an editor such as poedit to check that the translations have been correctly generated. You may also spot some incorrect / imprecise translations (e.g like 'Easter Island' mentionned above). In that case, you can override the CLDR translation by providing an entry in the overrides/your_language file.

Step 6: Add your name to the contributors list

So that you can easily be contacted when there is a line to add to overrides/your_language, for example when pytz is updated. Just add the language and a way to contact you.

Step 7: Increase maintenance version number and create a pull request

You just need to increment the 3rd number of the version (as the major and minor must match pytz's version) before creating a pull request.