agentleFS
FracteraFractera/Agent-Engineering-Infrastructure/.claude/skills/use-translations/SKILL.md

use-translations

Skill68 starsChanged 2 days agoMITView on GitHub

Where a translatable string is allowed to live, how many languages it owes, and who checks. Load it before adding ANY user-visible string, before creating a dictionary, when a gate says a dictionary is short of languages, when the owner says "translate this" or "why is this page English", and before promising him a translation run. Three storage forms exist and they are not interchangeable; the number of languages is decided by WHAT the thing is, not by how important it feels; and the guard only checks the dictionaries somebody registered by hand — which is how two dictionaries stood outside it for weeks while looking perfectly healthy.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

use-translations

Informational, not binding. Know a better way for the case in front of you — do it your way and say so. You are trusted with the creative work on this project.

A string is never written where it is used. Everything below is about choosing its home, its language count, and its guard — three decisions taken before the string exists, because moving one afterwards means touching every file that reads it.


1. 🔒 Three forms, and they are not interchangeable

FormLooks likeBelongs toGuarded by
dictionaryone file, lang → { key: string }interface words: buttons, labels, empty states, errorscheck:i18n, if registered
language cella folder, one file per language (_data/en.ts, ru.ts)the CONTENT of an authored page: a post, a legal page, the home pagecheck:i18n via its own list, if registered
object columnan i18n column in the row itself (lib/products/localize.ts reads it)the content of a thing somebody created: a product, a categorynothing — the person who made the object owns its languages

Choosing wrong is expensive in one direction: interface words inside a language cell get copied into every page that shows the same button, and they drift. Page prose inside a dictionary turns a file meant for short labels into a document nobody can review.

🔒 lang === "ru" ? … : … is not a third option. It cannot be exported, cannot be counted by a gate, and is found by the person least expecting it — a visitor on the language you never opened.

2. 🔒 How many languages — decided by WHAT it is

The thingLanguagesWhy
a reusable part of the product — appears anywhere the owner switches a language on82it shows up in a new language the same minute it is enabled, with nobody editing anything. Arriving there in English means that part is broken in every new market at once
words of one page or one widget10the page set; a widget belongs to one route and never appears by itself
content of an objectwhoever created itnot our decision at all

Cookie consent is the sharpest case of the first row: consent shown in a language the visitor does not read is not a rough edge, it is consent that did not happen.

🔒 Fewer than the row says is legal ONLY as a written debt — a line in development-docs/TRANSLATION-DEBT.md and the honest number in scripts/check-i18n.mjs. Two dictionaries carry 2 today and both are written down. A number that lies to look finished is worse than the debt: the next session reads the gate as truth.

3. 🔒 The guard checks only what somebody registered

scripts/check-i18n.mjs holds two hand-written lists — dictionaries and language cells. A file not on a list is not checked at all, and nothing says so out loud.

This is not an oversight to fix with a folder walk. A walk would silently adopt files nobody decided about, and the decision — how many languages this thing owes — is exactly what must be made consciously. The cost is real and was paid: two dialog dictionaries already carried 82 languages while standing outside the guard, so they could have been cut to ten and no gate would have noticed.

Therefore: registering a new dictionary is part of the same commit as the dictionary. Not a follow-up task.

🔒 check:i18n does NOT run in prebuild. It and check:types are the two you run yourself (use-code-shape §2).

4. Translating a lot at once — the owner's route, not yours

Translating page prose by hand is paid for in context on every iteration. The project has a pair of scripts for handing the work to an external model:

node scripts/i18n-export.mjs <dict> --langs uk,cs,sk    → storage/i18n/<dict>.request.json
node scripts/i18n-import.mjs <dict> <answer.json>       → writes back, only if every check passes

Three limits worth knowing BEFORE you promise anything:

  • Only registered dictionaries, and only JSON ones. DICTS in the export script lists them; a .i18n.ts dictionary is not among them. Wrong name → the script prints what it does know and stops.
  • There is no default language list. --langs is mandatory; without it the script refuses rather than guessing a set.
  • The import does not trust the model, and that is its whole point. It refuses a missing key, a changed placeholder ({roles} translated as {роли} breaks the page silently in exactly the language nobody opens) and an answer that is not an object of languages. Nothing is written until every check passes.

🔒 A translation run is the owner's decision, not a chore you start. Proposing one for strings he did not ask about spends his money on work nobody ordered — and mid-development those strings will be rewritten anyway.

5. When to translate at all

Develop in the default language; translate when the thing is finished. During construction the same string is rewritten several times, and every rewrite pays for the translation again.

That rule has a second half, and forgetting it is what makes it dangerous: the postponed translation disappears from view together with the step. Write the debt down the same day, in TRANSLATION-DEBT.md, or in a month nobody can say which routes are still single-language.

6. Machine strings are never translated

Ids, slugs, enum values, data-* attributes, config keys, product names in the do-not-translate list (Fractera, GitHub, OpenAI, Next.js, …). A translated identifier does not look wrong — it looks like a working page until something searches by it.

7. Before you call it done

  1. npm run check:i18n — nobody runs it for you, and it is not in prebuild.
  2. The new dictionary is registered in scripts/check-i18n.mjs in this commit, with the number of languages it owes.
  3. Any shortfall is a line in TRANSLATION-DEBT.md, and the gate's number matches reality.
  4. Open the page in a language you did NOT write — the second one is enough. An untranslated string shows itself instantly there and never in the language you were building in.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.