ui-localization

Localizing a Web App's UI From Its Source Code

Prepare a web app's UI for translation by using its source code as the primary context. The deliverable is a localization plan: a code-aware string inventory, a terminology/glossary draft, and the list of structural problems that must be fixed before translation. It is not the finished translations — producing this plan is what makes the eventual translation safe, consistent, and free of nasty surprises.

The one idea that makes this skill worth using

Read the code, not just the strings. Two reasons:

1. Short strings are ambiguous alone, unambiguous in context. "Open", "Apply", "Free", "Close" each have several meanings; the component, the click handler, and the neighbouring strings tell you which one. A translator handed a flat list guesses; you don't have to.
2. The expensive failures aren't mistranslations — they're structural, and they live in the code. Code that picks a wheel-slice colour from the first letter of the translated label. A font with no glyphs for the target script. A layout whose box sizes are tuned to English word lengths. Dates that follow the browser locale while the UI follows the app locale. A naive {{var}} replacer with no plural support. None of these show up in a string catalog. You only catch them by reading the code — and they are the difference between a localization that ships and one that embarrasses.

A generic translator stops at #1 and misses #2 entirely. The structural sweep (Phase 4) is the heart of this skill; treat the rest as the scaffolding that makes it actionable.

Scale the depth to the job

A request to "add a Spanish locale" to a 30-string settings page does not need a 20-document audit. A full multi-locale program for a customer-facing product does. Match the output to the ask:

• Small / focused → codebase map (brief) + string inventory + technical-element notes + blockers + a short plan. One document is fine.
• Large / multi-locale / customer-facing → the full artifact set in references/artifact-templates.md, split into per-area files.

When unsure, start lean and offer to go deeper. Don't bury a small job in ceremony.

Checklist

Track these as tasks and work them in order. Phases 1–3 are mechanical discovery; 4 is the differentiator; 5–6 turn findings into decisions and a deliverable.

1. Scope & discover — confirm intent/locales with the user; map how the app stores and renders UI text.
2. Inventory strings with code context — trace each user-facing string to where it's defined and used.
3. Protect technical elements — find everything that must survive translation unchanged.
4. Catch structural blockers — run scripts/i18n-sweep.sh, then open and verify each lead (the crown jewel).
5. Draft glossary & surface product questions — terminology, from strings and code.
6. Assemble the deliverable + plan — readiness report + prioritized blockers + critical-strings register + open questions + next step.

digraph ui_localization {
    "Confirm scope & locales" [shape=box];
    "Map the codebase" [shape=box];
    "Inventory strings w/ usage" [shape=box];
    "Protect technical elements" [shape=box];
    "Sweep for structural blockers" [shape=box];
    "Draft glossary + questions" [shape=box];
    "Assemble plan; hand off to translation" [shape=doublecircle];

    "Confirm scope & locales" -> "Map the codebase";
    "Map the codebase" -> "Inventory strings w/ usage";
    "Inventory strings w/ usage" -> "Protect technical elements";
    "Protect technical elements" -> "Sweep for structural blockers";
    "Sweep for structural blockers" -> "Draft glossary + questions";
    "Draft glossary + questions" -> "Assemble plan; hand off to translation";
}

The process

Phase 1 — Scope & discover

First confirm the goal with the user: which target locales, what kind of product, the desired tone, and whether they'll do the translation later or want this plan to feed external translators. They often can't judge target-language fluency — so frame everything you'll later ask them around product meaning and release decisions, never grammar.

Then map the codebase by reading it (don't infer from folder names):

• Framework and any i18n library (react-i18next, next-intl, vue-i18n, lingui, formatjs, or none).
• Where translatable text lives: locale catalogs (/locales, /i18n, /messages) and strings hardcoded inline in components. Apps with no i18n setup keep everything inline — then part of your job is pinpointing the extraction sites.
• The translation call pattern: t(), i18n.t(), <Trans>, $t, useTranslation, etc.
• Routes/pages, the main UI areas, and the locale source (URL segment? config? Accept-Language? none yet?).

Produce a Codebase Localization Map and a one-paragraph Scope Summary (see references/artifact-templates.md). Confirm with the user: target locales, tone/formality, and which product names stay untranslated, before going deep.

Phase 2 — Inventory strings with code context

For each user-facing string, record where it's defined, where it's used, the component, the UI element type (button / menu / label / placeholder / tooltip / toast / dialog / validation / empty state), the action or event it sits next to, nearby strings, any placeholders, and how often it's reused.

The point is disambiguation: when a string's meaning is unclear, the code resolves it. And watch for the reuse trap — one source string used in two places with different meanings (e.g. common.open as both "open a file" and a status of "open"). One translation rarely fits both; recommend splitting the key. Flag these in a Reuse Risk list.

Phase 3 — Protect technical elements

Detect everything that must pass through translation untouched: interpolation ({name}, {{count}}), ICU message syntax, printf (%s, %1$s), HTML/JSX tags, markdown, URLs, emails, keyboard shortcuts, escape sequences, and embedded \n that drives layout. Use the code to learn what each placeholder means — t("invite.sent", { email: user.email }) tells you {email} is an email address, and t("upload.done", { count: files.length }) tells you {count} needs plural rules. Capture a Placeholder Meaning Map so a translator (or you, later) treats each variable correctly.

Phase 4 — Catch structural blockers (the crown jewel)

This is where the skill earns its keep. Sweep the code for the traps that break or embarrass translations even when every string is translated perfectly — styling/logic derived from display text, font/script coverage gaps, browser-vs-app locale drift, naive interpolation, missing pluralization, RTL hazards, text-transform case bugs, sentence-fragment markup, hardcoded strings, number/date/money formatting, and broken locale loading/registration (a whole locale silently failing to load, or a date library never registered for it — often the highest-severity issue in an otherwise-mature app).

Start with the bundled sweep: run scripts/i18n-sweep.sh <app-source-dir> (point it at the app root so it sees index.html too). It greps the whole catalog of traps at once and prints candidate sites grouped by category — so you never re-derive the search or forget a category. The output is leads, not findings: a grep hit isn't a blocker until you open the file and confirm the code actually does the risky thing (and hand-built formatting like a literal $ in JSX won't always match — read around each hit). Note too that some blockers are absences the grep can't show: no dir plumbing, a font with no glyphs for the target script, a missing locale source. Use the sweep to anchor coverage, then reason about what isn't there.

Read references/structural-blockers.md alongside it — it's the catalog the sweep is built from: why each category breaks localization, the code signals, and how to flag it. These findings are usually the most valuable part of your deliverable, because they're invisible to anyone working from the string catalog alone.

Be precise, and stingy with numbers. Counts are the easiest thing to get wrong and the easiest for a reviewer to disprove — and one bad number taints the whole report. So: (a) default to qualitative scope ("widespread", "a handful", "one") and only cite a number when it genuinely strengthens a finding; (b) when you do, run the exact command at report-time and paste its output, naming precisely what it counts — e.g. rg -l '$i18n.t(' src | wc -l → "307 files use t()" — never a remembered or estimated figure; (c) never cite the sweep's category totals as facts — those are lead counts (candidate lines for triage), not blocker counts, and they conflate scopes; (d) don't attach a number to a noun you didn't count — "584 components" when you actually counted files is the classic miss. Trace a behavior through its whole code path before claiming how it fails. On a mature codebase, a short list of verified, correctly-scoped findings beats a padded one — credit what's already handled, so the reader trusts what you flag.

Phase 5 — Draft glossary & surface product questions

Extract candidate terms from both the strings and the code — route names, component names, entity/model names, feature folders, repeated UI labels. Group them (core product concepts, navigation, actions, account/billing, statuses, errors, non-translatable terms) and mark each translate-or-keep. Then write the terminology questions for the user — always about product meaning, never language fluency. Good questions: "Is Workspace a generic concept or a branded feature name?" "Does Remove mean remove-from-list while Delete means permanent?" Note where the same concept is named two ways in the copy (e.g. "odds" vs "multiplier") so translators don't diverge.

Phase 6 — Assemble the deliverable + plan

Pull it together into a readiness report (structure in references/artifact-templates.md): scope, codebase map, string inventory, placeholder/technical map, glossary draft, prioritized structural blockers, open product questions, and a translation plan — recommended i18n approach (e.g. adopt an ICU-capable library if interpolation is naive), what to fix before vs. during extraction, and per-locale risks (length expansion, plural complexity, formality, script/RTL). For multi-locale work, resolve the code-derived product decisions once and note they apply to every locale; per-locale, capture only what differs.

Single out the critical strings. Some text carries consequences far beyond layout: destructive actions (delete / remove / reset / cancel), payments and billing, legal and compliance copy, security and privacy warnings, account changes, and permission prompts. A mistranslation here isn't a cosmetic bug — it can make a user delete the wrong thing or misunderstand what they're agreeing to, so it's the most expensive error in the whole job. Pull these into a short critical-strings register in the deliverable, flag them for careful, unambiguous wording, and recommend a back-translation check for them in the translation step — that lets the user sign off on meaning even in a language they don't read. The cost is reading the language they don't read. This matters because it's exactly the judgement a string catalog erases: "Delete workspace" and "Close" look like ordinary short labels until you notice one is irreversible.

End by stating the boundary plainly: this is the plan; executing the translation is the next step, and this document is what makes that step safe. Don't silently start translating — the user scoped this to the analysis.

Working with vs. without an existing i18n setup

• Has locale catalogs + t() → the inventory is key-based; cross-check that every key used in code exists in the source catalog and flag unused/orphaned keys.
• Strings hardcoded inline (no i18n yet) → the inventory is the extraction list; each entry is a future key. Recommend a key-naming scheme and an i18n library as part of the plan. (docs/i18n-strings.md in this repo is a worked example of exactly this case.)

Key principles

• Read the code, not just the strings — usage resolves ambiguity; the catalog can't.
• Structural blockers over mistranslations — the code-level traps are the costly, invisible failures; hunting them is the main event, not an afterthought.
• Ask about product meaning, not language fluency — the user may not speak the target language; never ask them to judge grammar or naturalness.
• Guard the consequential strings — destructive, billing, legal, security, and account copy gets a back-translation and extra care; a wrong word there is the costliest error in the job.
• Precision over volume — be stingy with counts (prefer qualitative scope; cite only a number you re-derived at report-time for exactly the thing you name); trace full code paths. A few correct, well-scoped findings beat a long list with inflated numbers or half-traced behavior.
• Scale depth to the job — one lean document for a small page; the full artifact set for a program.
• The deliverable makes translation safe; it is not the translation — stop at the plan unless asked to go further.

Bundled files

• scripts/i18n-sweep.sh <app-source-dir> — runs the whole structural-blocker grep sweep at once and prints candidate sites grouped by category. Run it at the start of Phase 4; treat output as leads to verify.
• references/structural-blockers.md — the catalog the sweep is built from: how to detect each trap, why it breaks, how to flag it. Read this for Phase 4 (and keep it open during Phase 2–3 — some traps surface while you inventory).
• references/artifact-templates.md — formats for every deliverable (codebase map, inventory columns, reuse-risk and placeholder maps, glossary, terminology questions, critical-strings register, the readiness report, recommended file layout). Pull the ones the job needs; ignore the rest.