Nyby Internationalization (i18n) tool

Translations, in both the server side and client apps, are embedded in the code using string keys. Since the source code are simply javascript, we use Babel to extract the keys from the code.

Setup

Create an i18n.json similar to i18n.example.json. API key can be set from environment variable I18N_API_KEY. Then call the following and following the prompts.

node dist/index.js i18n.example.json

The translation strings support ICU message format.

Translations

The source of truth for the translation keys and strings are stored in Crowdin. This allows us to use the translation keys and strings to integrate with other tools and systems, e.g., figma.

To add and/or remove keys, simple add and remove the keys in the main language file, typically en.i18n.json. To synchronize the new keys to Crowdin, simply run yarn i18n upload. To get updated translation strings and key from Crowdin, simply run yarn i18n download.

The provided yarn i18n extract tool can extract and add new keys from the source code and gives warning to keys that are no longer used in the code. Keys can be added manually be editing the main language json file.

yarn i18n missing takes those warnings the rest of the way: it lists the keys the code no longer uses, offers to drop them from the language files, takes this project's label off them in Crowdin, and hands what is left to yarn i18n stale.

To fill in translations, yarn i18n todo <strings.tsv> writes every string some language is still missing, one column per locale. Fill in the blank cells and yarn i18n translate <strings.tsv> posts them as unapproved suggestions for a translator to confirm.

yarn i18n glossary <terms.tsv> derives the terminology the translations already use, since every key is one segment across all the languages. Set terms in i18n.json and download keeps that file up to date alongside sourceText, so the glossary in the repo always describes the translations it came with.

yarn i18n check reports everything the other commands would change without changing anything: keys the code uses that the main language file has not got, keys the file still holds that the code dropped, keys Crowdin has never seen, how much of each language is untranslated, and any message that will not parse or whose placeholders have drifted from the source. It names the command that fixes each group and exits non-zero when there is anything to do, so it works as a gate in CI.

yarn i18n term <text> shows how the product already says something, in every language at once. Worth asking before writing a new translation: the wording around a string is what decides whether it reads as part of the product. It reads only the local language files, so it is instant.

Run yarn i18n with no command for the full reference; every command says whether it writes local files, Crowdin, or nothing.

Running it without a person at the keyboard

Everything that writes asks first. When there is no terminal to ask in, the confirmation is declined and says so, rather than quietly doing nothing and reporting success.

| Option | | | --- | --- | | --dry-run | Print what each step would write, write nothing. Overrides --yes. | | --yes | Answer the ordinary confirmations. Deleting keys or strings and rewording English still need a terminal. | | --json | Machine-readable output for the commands that report. Progress moves to stderr, so stdout is only the report. | | --fresh | Skip the cached Crowdin download and fetch again. | | --mine | Only the keys this config uses, for a Crowdin file several projects share. |

Read-only commands cache the Crowdin download for ten minutes, so a second command in a row starts immediately instead of spending a minute downloading the same file. Anything that writes to Crowdin always fetches fresh and clears the cache afterwards.

With yarn, use yarn --silent for --json so yarn's own banner stays off stdout.

Updating the strings in the main language file will invalidate the translated strings in the other languages. This can be done using yarn i18n upload tool to upload the updated main language file strings to Crowdin. Invalidating the strings will inform the translators that new translations are required. The main language strings can also be changed and invalidated in the Crowdin app itself.