# Practical Localizer > Use when adding a locale or language, translating or reviewing locale files, fixing plural, date, number or currency formatting, right-to-left layout, or asking whether translated copy sounds natural. Writes natural, context-aware product copy rather than literal translation, and keeps placeholders, ICU plurals, locale formatting and terminology intact. Modes: analyze, localize (locale resources… - **Type:** Skill - **Install:** `agentstack add skill-soumyarauth-skills-hub-practical-localizer` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [soumyaRauth](https://agentstack.voostack.com/s/soumyarauth) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** https://github.com/soumyaRauth/skills-hub/tree/main/skills/practical-localizer - **Website:** https://soumyarauth.github.io/skills-hub/ ## Install ```sh agentstack add skill-soumyarauth-skills-hub-practical-localizer ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Practical Localizer A technically correct translation is not necessarily a natural one. For every string, answer the product question rather than the dictionary question: > Not "what is the translated word?" but > **"what would a real user of this language expect this product to say here?"** The deliverable is a **localization decision** per meaningful string — strategy, evidence, confidence — not a bilingual word list. ## Activation **Engage when** a locale or language is added; locale resources are translated, reviewed or changed; plural rules, date, number, currency or unit formatting, or right-to-left layout are involved; or someone asks whether translated copy reads naturally. **Stay quiet when** English copy changes in an app with no translation catalogs. A copy change that is not localization work gets no localization commentary. **Depth** `ACTIVE` in its three modes. `CONSULT` in one case: source copy changed for a key other locales already translate. Add one line naming the catalogs that now hold the old meaning, and do not touch them. **Composes with** `proof-driven-dev` (hardcoded strings, concatenated plurals and formatter bugs are source changes, handed over rather than fixed here) · `production-guard` (localizing what already ships) · `standards-compass` (accessible names and document language stay its call). ### Working with the other Skills Hub skills - **Loaded is not engaged.** This file stays in context once loaded. Decide again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not. - **Depth.** `PASSIVE` informs judgment and adds nothing to the reply · `CONSULT` adds a few lines that change what gets built · `ACTIVE` shapes the work · `GATING` decides whether something proceeds, and only when a person asked for that decision. - **Announce once.** When any skill engages at `CONSULT` or above, open the reply with one line such as `⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data`: names and a few words of reason. Never include reasoning. Add no line for `PASSIVE`, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: ` dropped: `. - **One interruption per request.** Skills that must speak before the work share one short block. Everything else arrives with the work. - **Hand off; don't absorb.** When another discipline is needed, write `HANDOFF → : []` and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so. - **Conflicts.** User intent, then project context, then engineering risk, then applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's. - **Overrides.** "Use X" engages X. "Skip X" or "no review" drops X's ceremony. Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line. - **State.** Read what sibling skills recorded (`.project-compass/`, `.project-standards/`, `.proofbuild/`, `.agent-investigation/`) rather than re-deriving it. Write only your own. - **Lessons.** On engaging, read `~/.skills-hub/lessons/.md` if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: `- YYYY-MM-DD · — `. Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say `Lesson recorded: ` once; if the file cannot be written, give the lesson in the reply instead. ## Non-negotiable rules 1. **Context before translation.** Never translate an isolated string when the application can be inspected. A key, its call sites, its component, its neighbouring copy and its UI role all change the answer. See `references/context-analysis.md`. 2. **Never break the localization infrastructure.** Keys, nesting, placeholders, ICU expressions, HTML/Markdown, escapes and formatting tokens survive unchanged. A translation that loses `{{name}}` is a defect, not a style choice. 3. **Existing project terminology wins.** If the app already says `লগইন` in twenty places, a new, better-sounding synonym is an *inconsistency*, not an improvement. Change established terminology only deliberately, everywhere at once, and say so. 4. **Evidence and humility.** Never claim "native speakers say this". Say "this is the more common software convention" or "this is likely more natural in contemporary product usage", and name what the claim rests on. See `references/confidence.md`. 5. **Surface uncertainty instead of guessing.** Missing gender, unclear plural context, ambiguous source term, culturally loaded copy → mark `REVIEW REQUIRED` and keep going. Silence is the failure mode. 6. **Scope discipline.** Modify localization resources only, and only in LOCALIZE mode. Never rename variables, functions, routes, CSS classes, database columns or test identifiers. Never edit layout or CSS for RTL unless explicitly asked — report the need instead. 7. **No fabricated numbers.** Report counts you actually produced. "Several strings" beats an invented total. 8. **Quality over volume.** Forty strings that sound like the product beats four hundred that sound like a dictionary. ## Modes Pick the mode from the request; state which one you are running before starting. | Mode | Trigger | Writes files | | --- | --- | --- | | **ANALYZE** | "analyze this app for X localization", "are we ready to ship in X?" | No | | **LOCALIZE** | "localize this app to X", "translate the missing strings" | Locale resources only | | **REVIEW** | "review the X localization", "does this sound natural?" | No — recommendations only | If the request is ambiguous, run ANALYZE and offer the other two. Never write files in ANALYZE or REVIEW mode, even when the fix looks obvious; propose the change and let the user ask. ## Workflow Phases 1–6 run in every mode. Phase 7 is LOCALIZE-only. Phases 8–10 run whenever there are translations to check — produced or pre-existing. Skip a phase explicitly rather than inventing content for it. ### Phase 1 — Understand the request Establish: source locale, target locale(s), region if it matters (`pt-BR` vs `pt-PT`, `zh-Hans` vs `zh-Hant`), scope (whole app, one namespace, one file, the diff), mode, and who the product's users are. Compress it into one **LOCALIZATION STATEMENT**: > Localize the checkout flow of a consumer e-commerce app from `en` to `bn-BD`, > matching the existing informal-polite tone. If something is ambiguous, choose the most reasonable reading, state it under `INTERPRETATION`, and continue. ### Phase 2 — Localization reconnaissance Learn how *this* application does localization before touching it. Read the manifests, then find the actual mechanism: JSON/YAML catalogs, TS/JS message objects, i18next, react-intl/FormatJS, next-intl, next-i18next, Laravel `lang/`, gettext `.po`, Rails I18n, Flutter `.arb`, Android `strings.xml`, iOS `Localizable.strings`, or something custom. Never assume a framework or a directory. Look. When the repository contradicts convention, the repository wins. See `references/localization-workflow.md`. Record: message format, placeholder syntax, plural mechanism, namespace layout, locale list, fallback locale, and how the app formats dates, numbers and money. ### Phase 3 — Build the language usage profile Before substantial work, build a working profile of the target locale: script, direction, formality and pronoun conventions, plural categories, how software vocabulary is normally handled (translated / transliterated / kept in English), date-time-number-currency conventions, punctuation and quotation marks, and the terms that are known to be contested. Treat it as a set of *factors*, not laws. Regional, generational and product variation is real — never encode "language X always ...". Start from `templates/locale-profile.yml`; a profile the user supplies overrides your assumptions. ### Phase 4 — Harvest existing terminology Existing high-confidence translations are translation memory. Extract the target terms already used for recurring product concepts, count where they appear, and note conflicts — two target terms for one concept is a finding. Build a working glossary (`templates/glossary.yml`): source term, target term, strategy, context, confidence, notes. Reuse it for the same concept in the same grammatical role; do **not** reuse it blindly when the role or sentence structure differs. See `references/terminology.md`. ### Phase 5 — Extract context per string For each string that carries meaning, gather what the repository knows: the key path and namespace, the component and function names around the call site, nearby copy, whether it is a button / label / heading / status / error / placeholder / tooltip / aria-label, the action it triggers, and any comments. `t("remove")` inside `removeMember(member)` is "remove this member from the team", not "delete permanently" — and many languages need that distinction where English does not. Watch the classic ambiguous terms: Save, Remove, Delete, Cancel, Submit, Apply, Back, Continue, Close, Open, Share, Account, User, Profile, Project, Workspace. If context cannot resolve it, mark `REVIEW REQUIRED`. See `references/context-analysis.md`. ### Phase 6 — Choose a strategy per term Every meaningful term gets exactly one strategy, with a reason: | Strategy | Use when | Illustration | | --- | --- | --- | | **TRANSLATE** | The language has a natural, current equivalent | Delete → a native verb form | | **TRANSLITERATE** | The borrowed source word *is* the word users say | Chair → চেয়ার | | **PRESERVE** | Translating would obscure meaning: identifiers, protocols, brands | API, JSON, HTTP, product names | | **ADAPT** | Word-for-word would be unidiomatic — reword for the same intent | "Get Started" → the local call-to-action | Choose from target language, UI context, existing project terminology, audience and product tone — never from a blanket rule such as "keep all technical terms in English" or "translate everything". The correct answer differs *between* languages for the same word. See `references/translation-strategy.md`. ### Phase 7 — Produce the localization (LOCALIZE only) Before writing: run `git status`, note pre-existing modifications, confirm the exact files in scope, and never touch anything else. Then, per string: copy the key and structure verbatim, translate the human-readable text only, preserve every placeholder and ICU construct character-for-character, and match the product's tone (`references/translation-strategy.md` covers tone matching). Prefer adding missing strings and fixing defects over rewriting acceptable existing translations. Never commit, push, checkout, reset, or discard user changes. ### Phase 8 — Technical validation Mechanical, blocking, and run on every translation you produced or reviewed: - **Placeholders:** the multiset of placeholders in source and target must match exactly — `{name}`, `{{name}}`, `${name}`, `%s`, `%1$s`, `:name`, `%{name}`, `…`. A mismatch is a **BLOCKING TECHNICAL ISSUE**. Do not silently "fix" one unless the correct form is unambiguous. - **Plural forms:** every category the target locale requires is present, and no invented ones. Never fake pluralization with string concatenation when the framework provides a mechanism. See `references/pluralization.md`. - **Structure:** keys, nesting and file syntax unchanged; valid JSON/YAML/XML/PHP; no lost escapes; no smart-quote substitution inside code or HTML. - **Markup:** HTML tags, Markdown and rich-text components intact and balanced. Report each as PASS or list the failures. Do not report PASS for a check you did not perform. ### Phase 9 — Naturalness and consistency pass Re-read the target text as a user of the product, not as a translator. For each non-trivial string judge: literalness (does it mirror English word order for no reason?), naturalness, product convention (does it sound like modern software?), consistency with the glossary, contextual accuracy, audience fit and tone. Anything below HIGH naturalness or HIGH context confidence goes on the review list. See `references/review-methodology.md`. ### Phase 10 — Locale mechanics Text is not the whole of localization. Check and report — do not silently change: - Date, time, number, decimal/thousands separators, currency placement and symbol, units, percentages. Prefer the platform's locale-aware mechanism (`Intl`, framework formatters) over hardcoded patterns. See `references/locale-formatting.md`. - Direction for RTL targets: layout assumptions, directional icons, left/right wording, mixed LTR content, punctuation. See `references/rtl.md`. - UI fit: expansion and contraction in buttons, nav, tabs, tables, badges and modal titles. Flag as `POTENTIAL UI FIT ISSUE` — never invent pixel measurements you cannot observe. See `references/ui-fit.md`. ## Report formats Show a count only when you actually produced it. Omit sections that have no content instead of padding them. ### ANALYZE ``` PRACTICAL LOCALIZER ──────────────────────────────── SOURCE English (en) TARGET Bengali (bn-BD) APPLICATION LOCALIZATION INVENTORY Source strings Existing translations Missing Naturalness concerns Terminology conflicts Technical issues LANGUAGE OBSERVATIONS TERMINOLOGY REVIEW REQUIRED RECOMMENDED STRATEGY ``` ### REVIEW One numbered entry per finding, highest confidence first: ``` LOCALIZATION REVIEW ──────────────────────────────── Target Bengali (bn-BD) Reviewed strings High-confidence issues Medium-confidence issues Technical issues #1 Key furniture.chair Source Chair Current কেদারা Recommended চেয়ার Category Naturalness / terminology Reason Dictionary-valid but reads as formal/literary for a modern app; the transliterated form is the more common product usage and matches সোফা / টেবিল already used in this file. Confidence HIGH ``` Categories: naturalness · terminology consistency · tone · grammar · placeholder · pluralization · locale format · technical term · transliteration consistency · should-stay-source · cultural fit · UI fit. ### LOCALIZE ``` LOCALIZATION COMPLETE ──────────────────────────────── Target Bengali (bn-BD) Files changed Added Updated Unchanged Placeholder validation PASS / Plural validation PASS / Structure validation PASS / Terminology consistency PASS / HUMAN REVIEW RECOMMENDED — ``` Follow with the glossary entries you established, so the next run stays consistent. ## Evidence and research When web access is available you may check uncertain terminology against reputable evidence: how major products localize the same UI concept, official platform localization glossaries, language authorities, quality dictionaries, and native-language technical writing. Prefer several converging sources over one, and never treat a machine-translation site as authority … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [soumyaRauth](https://github.com/soumyaRauth) - **Source:** [soumyaRauth/skills-hub](https://github.com/soumyaRauth/skills-hub) - **License:** MIT - **Homepage:** https://soumyarauth.github.io/skills-hub/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-soumyarauth-skills-hub-practical-localizer - Seller: https://agentstack.voostack.com/s/soumyarauth - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.