Write each language for its readers

Tale addresses readers as a helpful peer: you in English, du in German and Swiss German, and tu in French. Preserve that relationship and the complete meaning. A good translation uses the syntax and vocabulary a reader expects in their language; it does not preserve English sentence shapes merely because they came first.

Establish scope and sources

Read the repo contract, then the applicable locale guide: English, German, French, or Swiss German. For docs, also follow write-docs and the local content contract.

In the task's note outside the clone, identify the files, reader's task, meaning to preserve, terminology to verify, and likely language risks. Reuse an existing planning note; no additional notes skill is needed. For a broad change, track coverage by page and locale, including what has actually received a native-language read-through.

Use these sources for different questions:

• Product behavior: the observed running product, supported by current source and tests.
• Visible UI wording: the relevant service's message catalog plus shared UI messages, resolved through locale fallback. Match the exact displayed string when naming a control.
• Approved terminology: the glossary and its context notes. Read BUCKETS.md when a term may stay English.
• Typography and checks: CONVENTIONS.md, the locale guide, and the i18n test framework. Inspect actual check modes; advisory findings are not proof of correctness.

Find the key’s owner before editing. Reusable app controls keep messages in packages/ui/src/i18n/messages/; marketing frames use packages/marketing-ui/src/i18n/messages/; service-specific UI keeps services/<name>/messages/. The platform keeps one file per topic and locale — services/platform/messages/<locale>/<topic>.yml, a topic being one top-level namespace (chat.yml holds chat.*) — and every locale has the same files (de-CH only the ones it overrides), so a key lives in the same topic file in each locale. initServiceI18n merges package bundles in order, then service bundles per leaf key, with locale fallback and sparse regional overlays. Check overrides that can hide a shared correction. Moving a component also moves its owned keys and relevant regional overrides; it does not require a second service copy.

For browser locators, @tale/e2e/i18n accepts explicit package catalogs beneath the service catalog. Match the runtime package order. This helper does not interpolate ICU or apply locale fallback for you; supply the catalogs for the language the test actually renders.

When the source is ambiguous or wrong, resolve the meaning before translating. If the UI label is wrong, fix it and its dependent docs within scope, or describe the shipped label and record the issue. Do not silently invent a better label that readers cannot find.

Separate facts from language

Preserve permissions, scope, prerequisites, conditions, negation, defaults, limits, units, quantities, supported states, warnings, and recovery. “May”, “must”, and “can” are different claims. Keep brands and technical identifiers exact: message keys, placeholders, routes, filenames, environment variables, flags, enums, error codes, and JSON keys.

Locale is not jurisdiction or billing configuration. Never change a currency, amount, time zone, legal authority, certification, retention period, or contract promise to make it look local. Format a fact for the reader without changing the fact. If a style heuristic objects, inspect its scope and use the documented narrow exception with a reason; do not alter reality to pass lint.

For docs, preserve equivalent headings, warnings, components, code examples, images, links, and reader outcomes under the repository's parity checks. Rewrite sentences and paragraph breaks naturally inside that structure. All full locales supported by that tree ship together. Tale’s product guides have EN/DE/FR bodies; the design-system site currently serves English bodies even though its chrome catalogs include EN/DE/FR. Plain English example literals there follow its sample-code contract, not the product-message rules. de-CH remains a sparse overlay, not a fourth copied catalog.

Draft from meaning

Read a complete section, understand what readers need, then write it in the target language. Split a dense sentence, combine choppy ones, or move a qualifier when that improves clarity while preserving its scope. Use informal imperatives for instructions; use natural declarative sentences for explanations. Do not force every sentence to start with a verb or a purpose clause.

Keep terminology stable, but distinguish a UI label from an ordinary noun. A bold control name must match the catalog; a surrounding sentence still needs the target language's normal grammar. Translate navigation paths segment by segment. Do not leave English nouns scattered through a French or German explanation merely because a glossary includes a similar technical term.

Use the glossary workflow for a missing, contradictory, or context-dependent term. Prefer native wording a reader understands; approved loanwords should support comprehension, not replace it. A term can require different treatment in code, a quoted label, and ordinary prose. Do not apply broad search-and-replace to repair language.

Review messages and docs differently

UI messages: inspect the component and state that uses the key. Distinguish a button action, loading state, completion notice, empty state, and error. Match space and punctuation conventions for that surface. Preserve interpolation and ICU selectors; check zero, one, and multiple items, as well as grammatical agreement around substituted names. Never translate placeholder names. Preview changed controls for clipping, wrapping, accessible names, and focus behavior.

Documentation: read each translated section without looking at the English. Does it sound like native instructions, and could the reader complete the task? Then compare against the source for omissions, additions, altered conditions, and misleading claims. Check title, description, search terms, alt text, captions, component attributes, localized link prefixes, and translated anchors. Shared English screenshots do not license English control names in localized instructions.

For substantial rewrites, use an independent locale review when available. Give the reviewer the reader's task and the draft; ask for meaning, flow, terminology, and usability findings, not a literal back-translation. Resolve findings and track pages actually reviewed.

Verify and hand off

Run applicable locale/key/ICU and docs checks, then inspect the rendered result. Review report-mode findings as well as failures: they pass the suite and print as an i18n report-mode summary when it ends, which vitest shows only with --silent=false. Fix factual or grammatical defects; document a narrow exception only when a check is wrong for the context. Never weaken parity to make an unfinished translation pass.

The handoff states which locales and surfaces changed, the observed flows and checks, and remaining uncertainty. A fluent-looking page and a green suite do not establish native quality on their own.

For new locales, see GLOSSARY_GUIDE.md. This workflow follows Microsoft's global communication guidance while retaining Tale's own informal voice and product terminology.