Skip to content

Developer Guide

Jump to bottom
chrisgarrity edited this page Oct 23, 2020 · 3 revisions

Localizing Scratch

Setting up a new repository

There are two parts to localizing a new repository, extracting the source strings to be translated and syncing them with transifex, and pulling translations from transifex to be incorporated into the component.

Extracting source strings in React source files

Strings in the source are localized by using the FormattedMessage jsx component or calling formatMessage, and they can also be defined with defineMessages.

Adding new languages

See Adding a language.

If you are adding a language, do so before updating the translations (below).

Updating the current translations

Note that these instructions are often followed after following those at https://github.com/LLK/scratch-gui/wiki/Localization .

This can only be run by someone with developer credentials on Transifex.

Pull translations from Transifex

For the time being, we are not pulling everything that scratch-l10n is configured to request -- we just want the translations for a given Transifex project, like scratch-editor or scratch-website.

Sync editor translations:

> npm run pull:editor

or

> npm run pull:www

or

> npm run pull:blocks

etc.

Test translations

Test that the updated translations have no issues with json formatting by running npm test.

Create a pull request

Use git to commit these changes and push them to your fork on a branch named something like translations-<readable date>, such as translations-sep-18-2018.

Then create a pull request and request review. Note that the PR should be set to merge to the master branch.

When the PR looks good, merge it. Dependabot will automatically initiate updates to the packages that depend on scratch-l10n.

Adding a new translation resource to the l10n repo

Assuming that source strings have been extracted and sync'd to Transifex, here are the steps to add a new translation 'resource' -- a category of translations for a particular project.

  1. Add the new resource to .tx/config - for example, adding the pen extension strings:
[experimental-scratch.pen]
file_filter = pen/<lang>.json
source_file = pen/en.json
source_lang = en
type = CHROME
  1. Run tx pull -a -s to pull down all translations and the source file. [Note: this will also update other resources that have new translations. If you only want to update the new resource add -r 'experimental-scratch.pen' (i.e. the resource slug) to the command]
  2. Add the new component to the list of components in build-data.js The script assumes that the name of the component is the name of the folder that contains the translations.

Cron Jobs

There are two jobs that run on a schedule to sync translations. You can see the current status by viewing the scratch-l10n pipelines on circleci.com.

Daily Editor and Website update

CircleCI runs a weekly workflow called daily-tx-pull. It pulls updates translations for the editor (scratch-gui) and the website (www), commits those updates and publishes an l10n update on npmjs.

If the job fails:

  1. Click the Visit Job button to view the failing workflow on circleCI.
  2. Why did the job fail?
    • Invalid json file, or Test failure due to translation problem: work with ChrisG to fix the problem in transifex and notify translator
    • Transient network problem: e.g. bad gateway err 502. Rerunning the job will probably correct the issue. If not, work with ChrisG to figure out configuration problem.

Daily Help update

CircleCI runs a daily workflow called daily-help-update. It pulls translated Help Articles from Transifex and publishes them on Freshdesk. Nothing is saved in l10n.

If the job fails:

  1. Click the Visit Job button to view the failing workflow on circleCI.
  2. Why did the job fail?
    • Invalid json file, or Test failure due to translation problem: work with ChrisG to fix the problem in transifex and notify translator
    • Transient network problem: e.g. bad gateway err 502. This can be ignored unless it has happened for two days in a row.

Fixing typos in translated strings

When a source string is changed and pushed to transifex it invalidates all translations of the previous version of the string. If we've changed the meaning of the string or paragraph, that is the correct behavior. However, sometimes the change is to correct a typo in the English version, such as correcting a spelling error or missing punctuation. In those cases, usually the translator has translated the correct meaning, and it's frustrating to have to retranslate.

In transifex it is possible to modify a source string and keep the current translations. Here is the process to update the source string without invalidating translations:

  1. Make the change in the code, commit and submit PR.
  2. When the PR is "good to merge", correct the source string in Transifex, selecting the option to Save & Keep Translations not Save Changes.
  3. Merge the PR. It's important that the code change and the edit on Transifex happen on the same day. New translations are pushed daily to Transifex. If both updates are in sync, the string will match and the automatic update will not invalidate any translations. If the strings do not match for any reason, the update will invalidate translations.
Clone this wiki locally