Localization

Process for manually updating translations

You need a developer account on Transifex for this.

Install Transifex client

If you haven't already, install the Transifex client and follow instructions for generating an API token and running tx init. (Note that you may need to abort tx init partway through; the point is just to establish your Transifex API token locally.)

scratch-blocks

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

Push the source file to Transifex

Generate the English source file and sync it with Transifex. If there are new messages, remember to commit the new en.json.

> npm run translate
> tx push -s

Pull translations from transifex

If you already have json files for supported languages, pull updates. To be safe, use the -f force flag to update to the latest json for each language regardless of timestamp. You can leave off the -f and it will just update json for languages with updates since the last time it was sync'd.

> tx pull -f

tx pull only pulls down updates for languages that you already have in your json folder. If there are new languages to add run:

tx pull -l <locale>

for example, add Romanian tx pull -l ro

Note: if you have never pulled translations from Transifex, you will need to pull all the languages corresponding to the supportedLocales in scratch-l10n, and include the English source. To get an initial set run:

> tx pull -a --minimum-perc=80
> tx pull -l en

This will pull all the languages that have at least 80% of the blocks translated. You will need to remove any languages that do not yet meet the threshold for the editor overall. For example, they have 100% of the blocks translated, but only 50% of the gui.

Update the Scratch Messages file

Now that you have the latest json files, generate the new scratch-msgs:

npm run translate:update

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 instructions 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-*

Push all new strings to Transifex

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.

scratch-vm

> npm run i18n:src
> tx push -s

scratch-paint

> npm run i18n:src
> tx push -s

scratch-gui

> npm run i18n:src
> tx push -s

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)

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

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", ...}
    ...
}