Localization

Automation

• Scratch-gui, scratch-vm and scratch-paint have cron jobs that automatically push any source changes to transifex on a daily basis.
• Scratch-l10n has a cron job that runs weekly to pull new translations - check for failing jobs due to bad translations

Process for manually updating translations

You need a developer account on Transifex for this.

Set up Transifex

You don't need to install the Transifex client, but you do need to have an API token. The scripts expect an environment variable TX_TOKEN that is set to your API token.

You can install the client, but it requires python. Follow the Transifex instructions to install the client.

scratch-blocks

Scratch-blocks is outside of the scratch-l10n process, so it has to be handled separately.

Changes to source strings

If there are changes to the source strings in scratch-blocks, the source needs to be pushed to transifex, and default strings downloaded for all languages as part of the PR that introduces the change.

Generate the English source file. If there are new messages, remember to commit the new en.json.

> npm run translate

Push the en.json source file to transifex

> npm run translate:sync:src

Pull updated translations (including defaults for any added strings)

> npm run translate:sync:translations

For convenience, the push and pull can be run with one command:

> npm run translate:update

Updating translations

Update the scratch-l10n dependency to make sure we're pulling the correct languages.

Pull updated translations

> npm run translate:sync:translations

scratch_msgs.js should be the only changed file.

Note: if there are problems in the translations the last command will report them. For example, missing placeholders. You will need to fix the problems in Transifex, and then repeat the command to update translations.

Commit and push the changes to your fork. Create a PR. As long as the PR is just translation updates, it's fine to merge the PR without a review.

scratch-gui, scratch-paint & scratch-vm

Scratch-gui, scratch-paint and scratch-vm all use scripts imported from scratch-l10n to extract strings into an en.json source file and to push that file to transifex.

Extract strings from source files:

> npm run i18n:src

Push source strings to transifex:

> npm run i18n:push

Note: It's important to push new strings before you pull translations, as this will allow Transifex to include defaults (generally the English defaults you have provided) for new strings that have not yet had the chance to be translated.

Pull updated translations from Transifex

For the time being, we are not pulling everything that scratch-l10n is configured to request -- we just want the editor project's translations. To just update translations from the editor project we specify the resource with the -r 'scratch-editor.*' flag.

scratch-l10n

Sync editor translations (with -f to force update; then with -s to fetch the source language, English)

> tx pull -r 'scratch-editor.*' -f
> tx pull -r 'scratch-editor.*' -s

In scratch-l10n we can pull translations from transifex regardless of whether they're complete. The build step excludes languages that are not yet ready. However, if there are new languages that have been added in Transifex, they will need to be pulled explicitly the first time:

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

Alternatively, tx pull -r 'scratch-editor.*' -a will pull every language that's available in transifex. Languages can be added without adding them to the languages menu. This may be useful if a language is incomplete, but it's helpful for reviewers need to see the translations in context. When a language reaches 100% translated, it can be added to the menu. Edit supported-locales.js, to add a line to the locales const. If it's a language that has been translated on www, the name should be in the wwwLocales object. Otherwise find the name of the language as said in the language. We may need to contact the translators for this.

Important: further steps should be taken in the scratch-l10n repo to introduce new languages; see documentation there for instructions.

scratch-gui

Once the new versions of both scratch-blocks and scratch-l10n are available update the package.json to use the new versions.

Background

For all the repos other than scratch-blocks we're using Chromei18n json instead of just KeyValueJson because it includes a description field where we can add instructions for translators.

structure

• babel-plugin-react-intl generates messages files in build/messages/...
• translations/en.json is the combined messages (generated by build-i18n-src)

Example configuration for transifex:

> tx set --auto-local -r scratch-editor.interface translations/<lang>.json' -s en --type CHROME --source-file translations/en.json

This sets the translations/en.json file as the english source. Other translations pulled from transifex are expected to be in translations/<lang>.json We don't actually pull translations into the repo with the source, they all get pulled into scratch-l10n. scratch-l10n exports a combined messages file editor.js that has translations for all languages for gui (interface in Transifex), extensions (from vm), and paint-editor.

The combined messages looks like:

{ 
    "en": {"messageId1": "some string", "messageId2": "another string", ...}, 
    "es": {"messageId1": "some string in spanish", "messageId2": "another string in spanish", ...},
    "fr": {"messageId1": "some string in french", "messageId2": "another string in french", ...}
    ...
}