i18n-studio

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.