i18n Studio

Purpose

i18n Studio edits Astro-style i18n string files safely: files shaped like export default { en: {...}, ru: {...} } where leaves are UI strings. It writes one string literal at a time through a ts-morph AST, so every save is a minimal one-line diff with all surrounding formatting preserved, and a running dev server hot-reloads. It also produces Claude translation candidates that preserve HTML tags and tone.

Use it instead of hand-editing .ts string files with Edit/sed: manual edits risk formatting churn, broken quoting/escaping, and desynced languages. The AST layer avoids all three.

When to use

Filling in missing translations for a language (e.g. "translate the new hero copy to Russian", "fill the German gaps").
Auditing coverage ("which strings are untranslated?").
Editing UI microcopy in one or more languages.
Getting translation candidates for a specific string.
Opening a visual editor for a human to translate interactively ("open the translation editor").

Applies to any repo whose translations follow the export default { <lang>: {...} } convention, not one specific project.

Locate the strings directory first

The tool defaults to <cwd>/src/i18n/strings. Confirm the real location before starting (it may differ):

ls src/i18n/strings 2>/dev/null || find . -path '*/i18n/strings' -type d -not -path '*/node_modules/*' | head

Use that path as --dir below. Ensure the tool is installed once: cd ~/ai_projects/i18n-studio && npm install.

Start the server (required for the API and the UI)

Start it in the background, pointed at the target strings dir, and wait until it is reachable:

node ~/ai_projects/i18n-studio/server.mjs --dir "$PWD/src/i18n/strings" --port 4331 &
until curl -sf http://localhost:4331/api/strings >/dev/null; do sleep 0.5; done

Pass --langs en,ru,de if the corpus has languages beyond the en,ru default, and --voice "<one-line tone brief>" to steer suggestion style. Stop it with kill %1 (or the printed PID) when finished.

For a human to edit visually, start the server the same way and share the URL (http://localhost:4331); do not try to click the web UI programmatically.

Drive it with the helper CLI

scripts/i18n.mjs (dependency-free, Node 18+) wraps the API. Point it at the server with I18N_URL if the port is not 4331.

S=~/ai_projects/claude-skills/i18n-studio/scripts/i18n.mjs

node "$S" audit --to ru                          # status breakdown + untranslated/missing
node "$S" audit --to ru --pending                # also list translated-but-unaccepted
node "$S" get     Hero.ts en h1                   # read a value
node "$S" suggest Hero.ts h1 --from en --to ru    # 3 candidates (proposals only)
node "$S" set     Hero.ts ru h1 "Сначала — результат"  # AST-safe write (→ pending)
node "$S" accept  Hero.ts ru h1                   # mark reviewed/accepted
node "$S" unaccept Hero.ts ru h1                  # back to pending
node "$S" ignore  Dream.ts ru s2                  # mark n/a — "doesn't need translation"
node "$S" unignore Dream.ts ru s2                 # back to untranslated/pending

Typical translation-fill loop: audit --to <lang> to see the breakdown and gaps → for each gap, suggest from the source language → review the candidate (see rules below) → set the chosen value → accept once it is right.

Acceptance is a durable review state (sidecar .i18n-status.json); editing a value automatically drops it back to pending. A cell can instead be marked n/a ("doesn't need translation" — a name, a fragment, a shared token): ignore drops it out of the untranslated/pending gap counts so it stops nagging, and — unlike accept — works on an empty/untranslated cell. Like acceptance it is value-coupled, so translating the cell later re-surfaces it. For a human reviewer, the fullscreen review mode (below) is faster than the CLI.

The raw routes (GET /api/strings, POST /api/save, POST /api/suggest), data shapes, dot-path rules, config flags, and a no-server library path are documented in references/api.md. Read it before doing anything beyond the CLI above.

Visual editor: review mode, filters, duplicates

For a human, the browser UI is the fast path. Start the server, share the URL, and point out:

Source → target switch in the header (work any language against any reference).
Filters: show all / untranslated / pending / accepted / n/a / duplicates / code-like, by file, with sort (file / path / status / duplicates-first) and live counts.
Hide code-like: asset paths, CSS vars/colors, class names and identifiers are detected and hidden from the queue by default (they rarely need translation).
Accept and n/a buttons per row (and a duplicates badge ×N). The n/a toggle marks a string as not needing translation — it works even on empty cells and removes them from the untranslated queue.
Duplicate propagation: after editing a string that others shared, a banner offers apply to all — one click updates every entry that held the old value.
Fullscreen review (review ▸): steps through the filtered set one at a time, fully keyboard driven with a visible legend — ←/→ or j/k move, a accept & next, p pending, i mark n/a & next, e edit, s suggest, 1/2/3 apply a suggestion, u undo, Esc close, > focus. Tab lands on the edit field; clicking the file name filters the list to that file. This is the tool for grinding through thousands.
Focus mode (Shift + .): hides all chrome, leaving only the strings.

Rules that matter

Never blindly apply a suggestion. Before set, verify the candidate keeps the same HTML tags and entities as the source (<b>, <span ...>,  , ', —) in the same positions, and does not translate code identifiers or proper nouns. Suggestions are proposals, not decisions.
Interpolated strings are editable, placeholders are sacred. Template literals with ${...} come back editable: true, interp: true (badged ${…}); translate the prose but keep every ${...} placeholder exactly. Only non-string leaves (numbers, identifiers) stay read-only and must be edited in the .ts source.
Dot-paths use numeric indices for arrays, e.g. weeks.2.sessions.1.t.
One save writes one leaf. Loop for bulk work; there is no batch write.
Hot reload needs the target project's own dev server running; the write lands on disk either way.
Confirm before mass edits. Auto-translating a whole language is a large, outward-facing change to the product copy; surface the gap list and confirm scope with the user before writing many strings.