i18n Frontend Translate

When to Use

• User gives a locale (e.g. fr, pt-BR) and optionally instructions.
• Goal is to replace locale strings that still equal English with proper translations, using the repo scripts.

Preconditions

• Work from this repository root.
• lang/<locale>.json must exist. English source of truth is lang/en.json.

Workflow (loop)

1. User inputs: locale + free-text instructions (follow them for register, formality, product terms, and consistency).

2. List work: Run show-untranslated with a small batch so the task stays reviewable:

   npx tsx scripts/i18n/show-untranslated.ts <locale> --limit 30

   Increase --limit or re-run without --limit when draining the backlog.

3. Per string:

   • Read the line: {id}: {english}.
   • If meaning, audience, or UI role is unclear, find context before translating (see below).
   • If the string should stay English in this locale (same word in both languages, standard loanword, product name, etc.), do not run set-translation. Add the message id to IGNORED['<locale>'] in scripts/i18n/translation-stats.ts so it stops appearing in the report. Keep a short inline comment per entry (e.g. why it is not translated). Ignore matching is by id, not by English value.
   • Otherwise produce the target-language string that matches instructions and preserves placeholders/markup, then apply:

   npx tsx scripts/i18n/set-translation.ts <locale> <id> "Translation text"

   Quote the translation so the shell does not split words.

4. Repeat step 2 until show-untranslated returns nothing (or the user stops).
5. Sanity check: Optionally re-run show-untranslated for that locale; remaining lines should be actual translation work, or items intentionally listed under IGNORED.

6. Update progress: After finishing (or when the user stops), refresh locale completion percentages in lib/constants/locales.js:

   npm run langs:update-progress

Intentionally identical strings (IGNORED)

show-untranslated reports ids whose locale value still equals English, minus IGNORED for that locale. When a value is correctly left as English, register the message id under IGNORED in scripts/i18n/translation-stats.ts. Otherwise the loop never clears.

Finding context for a message id

Use when the English line alone is ambiguous (button vs heading, legal vs casual, technical sense).

• Search the repo for the id (appears in FormattedMessage, defineMessages, intl.formatMessage, etc.):

  rg -l '<id>' --glob '*.{tsx,ts,js,jsx}'

  Example: rg -l 'Ri4REE' --glob '*.{tsx,ts,js,jsx}'

• Open the matching file(s) and read surrounding UI: labels, modals, routes, audience.
• For duplicate or generic English, context disambiguates (e.g. "Order" as noun vs verb).
• Compare with other languages or en.json by searching lang/.

Preservation rules

• Keep ICU placeholders and rich-text tags exactly as in English unless the target language requires a different order: {name}, {count}, {amount}, <Link>...</Link>, <Account></Account>, etc.
• Do not invent new placeholders or remove required tags.
• Prefer consistent product terminology with the rest of lang/<locale>.json when the same concept appears elsewhere.

Scripts reference

Show-untranslated and set-translation are invoked with npx tsx from the repository root.