Translate Locales

When the user explicitly invokes this skill (e.g. @translate-locales), follow this 7-step workflow to regenerate the English locale from i18n modules, detect new or changed content, and translate it into four locales for the DApp.

Usage

• This skill is designed only for the batch workflow of exporting app/app/i18n/locales/en.json from the app i18n modules and translating new or changed keys (vs. the staged version of en.json) into zh, tc, ko, and es under app/app/i18n/locales/.
• If the user provides a specific JSON file or object to translate (e.g. a custom en subset or another locale to use as source), use it as the translation source and skip regenerating en.json and computing git diff (Step 2 and Step 3).
• Use this skill only when the user explicitly asks to generate and translate i18n keys for the DApp (e.g. @translate-locales or by name).
• Do not use this skill for general translation requests, ad-hoc string translation, or refactoring existing i18n keys.

Workflow

All shell commands below assume you start from the repo root. Step 1–2 run from the app directory; diff and merge steps refer to paths relative to the repo root.

Entry condition:

• If the user has manually provided JSON: The user has explicitly given a JSON file path (e.g. app/app/i18n/locales/xxx.json) or pasted/provided JSON object content, and has indicated that this JSON should be used as the translation source. In this case skip Step 2 and Step 3; use that JSON as the "English i18n JSON to translate" and go directly to Step 4 (check size and batch if needed), then Step 5 (translate), Step 6 (merge), and Step 7 (sync-locales).
• If the user has not provided JSON: Run the full sequence Step 1 → Step 2 → Step 3 → Step 4 → Step 5 → Step 6 → Step 7.

Step 1 – Navigate to app

• From the repo root, if the current directory is not app, run cd app. If already in app, skip.
• When the user has provided JSON and you skip Step 2 and Step 3, still ensure you are in (or will be in) the app directory before running Step 6 and Step 7.

Step 2 – Regenerate en.json

When the user has not manually provided a JSON file/object, run this step; otherwise skip and use the provided JSON as the input to Step 4.

• In app, run: yarn export-en-json
• This re-exports the en object from the i18n modules (see app/scripts/export-en-json.ts) into app/app/i18n/locales/en.json.

Step 3 – Detect new or changed content

When the user has not manually provided a JSON file/object, run this step to build the minimal diff JSON; otherwise skip and use the user-provided JSON as the input to Step 4.

• Ensure that the version of app/app/i18n/locales/en.json in the git index (staging area) represents the last confirmed canonical English locale (for example, staged after the previous successful translation run or commit). If not, stage that confirmed version first before proceeding.
• From the repo root (or from app with path app/app/i18n/locales/en.json), compare the current working copy of app/app/i18n/locales/en.json with the staged version in the index, e.g. run: git diff -- app/app/i18n/locales/en.json (no HEAD: diff is working tree vs staging area, not vs last commit). Git interprets this path relative to the repo root, so the command works even when run from app.
• Identify keys whose values are added or modified compared to the staged version of en.json (the last confirmed canonical version).
• Build a minimal JSON object containing only these new/changed key paths and values, preserving the same nested structure as in en.json.
• If there are no new or changed keys (diff JSON is empty), stop and inform the user that no translation is needed.

Step 4 – Check size and batch (if needed)

You have the JSON to translate (from Step 3’s minimal diff, or from the user when Step 2 and Step 3 were skipped). Check its size:

• If the JSON is empty or has no keys: Stop and inform the user that no translation is needed.
• If the JSON is large (e.g. more than 200 keys or more than 40,000 characters): Use batch translation to avoid exceeding the model’s token limit. From the user’s perspective this remains a single @translate-locales run; batching is handled internally.
  • Split: Split the JSON to translate into smaller batches of keys (e.g. 80–150 keys per batch), preserving the same nested key structure. You may split by key order or by top-level namespace.
  • Per batch: For each batch, use that batch’s JSON as the "English i18n JSON file" input to TRANSLATION_PROMPT.md and ask the model to produce the four JSON objects for zh, tc, ko, and es (same strict rules as in Step 5). Shallow-merge each batch’s four outputs into four accumulator objects (later batches overwrite same keys).
  • After all batches: Write the four accumulated locale objects to app/app/i18n/locales/diff-zh.json, diff-tc.json, diff-ko.json, and diff-es.json, then proceed to Step 6.
• If the JSON is small (within the thresholds above): Proceed to Step 5 and use the single-shot process there.

Step 5 – Translate new content with TRANSLATION_PROMPT

When the JSON to translate is small (within the threshold in Step 4), use this single-shot process:

• The "English i18n JSON file" input is either: (1) the minimal diff JSON from Step 3 (when Step 2/3 were not skipped), or (2) the user-provided JSON file/object (when the user skipped Step 2 and Step 3). Use that JSON as the content in the prompt defined in TRANSLATION_PROMPT.md (in this skill directory).
• Ask the current AI to produce four JSON objects for zh, tc, ko, and es, following the strict rules in the prompt (keys unchanged, placeholders/tags/newlines and token symbols preserved, etc.).
• Write the outputs to four per-locale diff files under app/app/i18n/locales/:
  • diff-zh.json
  • diff-tc.json
  • diff-ko.json
  • diff-es.json
• Each file must contain only the keys and values for that locale (no wrapper object like { "zh": { ... } }), preserving the same key structure as in en.json (for example):

  json
  1{
  2  "common.confirm": "Confirm"
  3}

Step 6 – Merge translations into locale files

• Use the built-in merge script at app/scripts/merge-translations.mjs. From the app directory, run:

  bash
  1node scripts/merge-translations.mjs

• The script looks for per-locale diff files diff-zh.json, diff-tc.json, diff-ko.json, and diff-es.json in app/app/i18n/locales/ and merges their keys into zh.json, tc.json, ko.json, and es.json respectively.
• These per-locale diff files are treated as temporary input; after the merge completes the script will attempt to delete each diff-*.json file, so they are not processed again by sync-locales or future merge runs.

Step 7 – Normalize locale files with sync-locales

• After Steps 1–6 are complete, ensure you are in the app directory.
• Run: yarn sync-locales.
• This command treats app/app/i18n/locales/en.json as the canonical key set and ordering, and for each other locale JSON file under app/app/i18n/locales/ it keeps only keys present in en.json and rewrites them in the same key order. If the user provided a custom JSON that is not a subset of the current en.json, keys that do not exist in en.json will be dropped from the locale files during this step.

Checklist

When the user has not manually provided JSON (full flow):

• In repo root, then cd app; yarn export-en-json run; app/app/i18n/locales/en.json updated as the latest canonical English locale
• Git diff inspected: git diff -- app/app/i18n/locales/en.json (working tree vs staging area, using the staged en.json as the last confirmed canonical version); diff JSON (new/changed keys only) prepared
• Step 4: If the diff JSON is large, use the batch flow (split, translate per batch, accumulate, then write once); otherwise go to Step 5 for single-shot; outputs written to app/app/i18n/locales/diff-zh.json, diff-tc.json, diff-ko.json, diff-es.json
• node scripts/merge-translations.mjs run from app (Step 6); per-locale diff-*.json files removed after merge
• In app, yarn sync-locales run (Step 7); non-English locale JSON files aligned to the key set and ordering of en.json, with any extra keys dropped
• Spot-check several languages to ensure placeholders, HTML tags, newlines, and token symbols are preserved and that key sets match the English source

When the user has manually provided JSON (skip Step 2 and Step 3):

• Ensure in app (or run Step 1) before merge/sync; user-provided JSON used as the translation source
• Step 4: If JSON is empty, stop; if it exceeds the thresholds, apply the batch flow; otherwise Step 5 single-shot; outputs written to app/app/i18n/locales/diff-zh.json, diff-tc.json, diff-ko.json, diff-es.json
• Step 6: node scripts/merge-translations.mjs run from app; then Step 7: yarn sync-locales in app
• Spot-check several languages to ensure placeholders, HTML tags, newlines, and token symbols are preserved and that key sets match the source

Built-in script

The merge script app/scripts/merge-translations.mjs is a permanent part of the repo. It runs in per-locale diff mode: when called from the app directory, it reads diff-zh.json, diff-tc.json, diff-ko.json, and diff-es.json from app/app/i18n/locales/ and merges their keys into zh.json, tc.json, ko.json, and es.json respectively.

Do not recreate this script; use the existing one.

Error handling

• If yarn export-en-json fails: verify the script and i18n module paths exist, run yarn install if needed, and check app/app/i18n/module/index.ts exports correctly.
• If the user-provided JSON is missing, invalid, or empty: ask for a valid JSON file path or object, or stop and explain that no translation is needed.
• If translation output is invalid JSON: validate the AI output (no trailing commas, no comments, proper escaping), and re-run translation if needed.
• If a locale file is missing: the merge script creates an empty object {} before merging.
• If merge-translations.mjs fails, ensure diff-zh.json, diff-tc.json, diff-ko.json, and diff-es.json exist under app/app/i18n/locales/ (or that missing locales are intentionally omitted), and that you are running the script from the app directory.
• If a single translation request fails due to token limits, switch to the batch strategy in Step 4 (split the JSON into smaller batches, e.g. 50–80 keys per batch, translate each batch, accumulate, then write the four diff files and run the merge script once).

When NOT to use this skill

• The user only wants to translate a small number of ad-hoc strings or UI copy.
• The user is refactoring or renaming existing i18n keys rather than translating new/changed keys.
• The task is general content translation unrelated to the DApp i18n JSON files.