Internationalization (i18n)

Unisubs has some complex requirements in terms of 18n. This is a rough guide of how things work.

Django’s system is gnu’s get text system. For example:


The first two letters are the language code, according to ISO 639-1. In this case Portuguese.

If the locale has variation as to the country, for example Portugal’s Portuguese vs Brazilian’s portuguese then the locale name is appended an underscore + the country two digit code, which is ISO 3166. Therefore the locales for portuguese speaking countries are:

pt_BR -> Brazilian Portuguese
pt_PT -> Portugal's Portuguese

Some of the less common languages are not covered by ISO 639-1 but are by ISO 639-3.


Most of the heavy lifting is handled by our Unilangs library.

Steps for adding a new language:

  • Figure Out the ISO code If ISO 639-1 covers it, it’s the prefered way to handle this, as it would keep our code streamlined with Django’s. If not, then we should prefer ISO 639-3. One can depend on the list of ISO 693-1 and the list of ISO 693-3 on Wikipedia.

    Also if it’s more of an uknown language it’s useful to look at the Wikipedia entry for it. Sometimes, we have a request to include a language that doesn’t make sense. For example there is no Norwegian(no), but there are dialects (nb and nn) that are used. Usually the Wikipedia page will discuss similar languages and specific dialects.

  • Update Unilangs INTERNAL_NAMES: Add the language code, the English name for the language, and the language in it’s own name to the file .

  • Update the unisubs standard: Add the language code to our standard .

  • Update other codecs: If django supports that locale (as in we can i18n the site’s UI) update the ‘dango’ standard. If other standards (such as ISO-693-1) support it, update them too.

Of course, once you’ve updated unlilangs, you’ll need to update the virtual envs on all installations of the app.

Updating Django

One must be careful when updating the Django’s version. As new locales are added between releases, we must check if the locale is already added on our end with a different encoding. If that happens, we’ll have duplication . This has beaten us before.


Different partners might have different language requirements while mapping to their own internal systems. We should update this guide once we have more specifics on how we’re implementing those mappings.