Adding a language

Preparation

Have a current transifex commandline setup

You should have a valid TX_TOKEN set to your transifex API key, either in your environment or ready to be put as a prefix to your commands. If you do not have a personal transifex maintainer account, there is a Dev Transifex account. Look for the credentials (API key) in the team password vault.

You will need to install the transifex command line tools (python) for the scratchr2 update if you do not already have them. To install the tx commandline tool, run:

sudo pip install transifex-client

At times we have had to force pip to install to a specific newer version, using:

sudo pip install -Iv transifex-client==0.13.6

Update scratch-l10n

Branch from master

Create a branch named something like "add Ukrainian"

Add the language to supported-locales.js

1. Add an entry to the locales const.

Note: always use the name of the language as written in the language itself, using the language's most common scrip. Example: Amharic is written 'አማርኛ'. We may need to contact the translators for this; Wikipedia is also useful.Omniglot language names is also helpful. It should be inserted in the list alphabetically according to how the name sounds. For example, Japanese sounds like 'Nihon', so it's between 'Nederlands' and 'Norsk'._

2. Add an entry to the rtlLocales if the language is right-to-left.

Add locale data for the language

Note: this will become obsolete when we upgrade to react-intl 3+ in the repositories that use scratch-l10n.

react-intl requires the predefined locale-data for any language being used. It defines the defaults for things like dates, numbers, etc. scratch-l10n includes a copy of all the locale data (src/locale-data/*) from [email protected], the last version of react-intl that included locale-data.

1. If the language is in ./locale-data
   • in src/locale-data.js, add an import for the language
   • src/locale-data.js, add the imported language to localeData list for export
2. If the language is not in ./locale-data we need to define a custom locale for it. Since we don't actually have the resources to translate and maintain everything that is in a locale-data file, we usually pick a 'parent' locale and use that one.
   • Add an entry in customLocales in src/supported-locales.js. If the parent language is not obvious, or potentially a sensitive issue, just use English. There are very few places that Scratch uses this data in any case.
   • If the parent language is not one that is already in supported locales, add the import/export for it in src/locale-data.js

Handle regional variations

In general Scratch tries to avoid regional variations of languages. For example, there is only one version of English, not en-US, eb-GB etc. If the language does have a country code, then the transifex locale will be in the form lang_COUNTRY. Browsers expect the locale to be in the form lang-country with a dash instead of underscore. We need to have a mapping between the two forms.

1. Add a new entry to localeMap in src/supported-locales.js. Format is '<browser-locale-string>': '<Transifex locale string>'
2. Add a new entry to the lang_map list in .tx/config [Note: we are moving away from the transifex command line tools, so eventually this will be unecessary]

Bump minor version number

In package.json, increase the minor version number for the version key by one. E.g., change "3.1.0" to "3.2.0". (The third number will be automatically replaced by npm when we merge to master.)

Commit code changes

Now commit the changes so far, so that it will be easy to see just the code changes later.

Pull updated language translations

Make sure you have the transifex cli tool installed, and a valid TX_TOKEN in your environment or on the commandline.

Use npm to run the script that pulls any new translations based on the languages in supported-locales.js.

> npm run pull:editor
> npm run pull:www

Test the translations

> npm run test

Commit translation string updates

To avoid merge conflicts in other languages ignore or discard translation string updates that are modifications to existing language files. Now commit the remaining changes.

Review and merge

You're now ready to review and merge the changes to scratch-l10n. The new release will be used in other repositories below.

Update scratch-blocks

scratch-blocks depends on scratch-l10n for the list of languages, but maintains its own translation strings. When a new version of scratch-l10n is published that includes new languages, the l10n dependency in scratch-blocks must be updated. Follow the instructions in the scratch-blocks wiki to add languages to scratch-blocks.

Update scratchr2_translations

Setup

Checkout scratchr2_translations.

Make sure you have the transifex cli tool installed, and a valid TX_TOKEN in your environment.

Makes sure you are on the master branch, and it is updated.

Branch from master and name your branch something like "add-french".

Pull translations

Manually pull files associated with the new language:

> cd legacy
> tx pull -l <lang-code>

Then commit these changes and create a PR. Review and merge it.

Update Scratchr2

scratchr2 needs two changes:

1. the list of languages in scratchr2 settings must be updated
   • Update LANGUAGES in settings/base.py using the information in supported-locales.js.
2. the version of the scratchr2_translations subrepo must be updated to the one just committted
   • in your local scratchr2, cd into the scratchr2_translations directory, checkout master, and pull from origin

Make a PR with these changes, review and merge.

Update scratch-www if needed

Www has it's own version of custom-locales. If we needed to edit l10n custom-locales, make sure the same change is made on www.

---

Manually pulling translations for a language

We are deprecating the transifex tx command line tools, but if you wanted to manually update a particular language you would run:

> tx pull -r 'scratch-editor.*' -l <locale>