forge-i18n-docs

Use when writing or fixing project docs (README, changelog) or i18n (meertalig).

SKILL.md

GitHub
<!-- Provenance: Forge-native core (written 2026-11-02 for), plus the SA-W1-B2 graft of 2026-11-05 in references/guides-and-reference-pages.md. Full table: the Provenance section at the end. -->

Forge playbook — Internationalization and technical docs

When to use

  • Use for: a multilingual site or app (NL + EN is the owner's default pair), adding a language, fixing hard-coded strings, plurals, dates, numbers or currency per locale, right-to-left support; and for writing or fixing a README, a guide or tutorial page in the project docs, an API reference page, a changelog, an architecture decision record (ADR) or a long technical manual (handover, onboarding).
  • Not for: SEO crawl and hreflang validation (forge-web-quality), PRDs and release notes (forge-prd), articles, blog posts and newsletters in the owner's voice (forge-long-form-writing), cleaning AI tells out of existing prose (humanizer).

Do not duplicate — defer to: forge-website / forge-fullstack / forge-mobile (the app itself), forge-web-quality (hreflang, sitemaps), forge-a11y (lang attributes are also an a11y criterion), forge-api (the OpenAPI/GraphQL contract is the source of the API reference).

Hard rules — i18n

  • No user-visible string in code. Every string lives in a message catalog keyed by a stable id; the source locale is complete and a check fails on a missing key.
  • ICU MessageFormat for anything that varies: plurals ({count, plural, one {...} other {...}}), select for gender or type, and placeholders. Never build sentences by concatenating fragments.
  • Format with the platform (Intl.*, CLDR), never by hand: dates, times, numbers, currency, lists, relative time. Store UTC and ISO values; format at the edge with the user's locale and time zone.
  • Layout survives translation: allow 30-40% longer text, use CSS logical properties (margin-inline-start, not margin-left) and support dir="rtl" when an RTL language is in scope.
  • Locale is explicit: chosen by URL (/nl/, /en/) or a stored preference, never only by IP. Every page sets lang; alternates are linked (hand-off to forge-web-quality for hreflang).
  • Machine translation is a draft. Mark it as such; a native speaker or the owner signs it off. Never ship invented legal, price or contact text in a language nobody checked.

Hard rules — docs

  • Docs describe what the code does now. Every command in a README is run before it is written down; every documented option exists. Stale docs are a defect.
  • Ask before creating new doc files unless the task asks for docs; prefer updating the existing README.
  • Accepted ADRs are immutable: a change of mind is a new ADR that supersedes the old one.
  • No secrets, internal hostnames or customer data in examples; use placeholders such as <YOUR_API_KEY>.

Workflow — i18n

  1. Detect the stack and its standard library: next-intl, i18next, react-intl (FormatJS), vue-i18n, Astro i18n routing, Flutter intl + ARB, Android and iOS string catalogs. Use what the project already has.
  2. Extract hard-coded strings into the source catalog (references/i18n.md for key naming and layout).
  3. Convert variable text to ICU messages; move formatting to Intl.
  4. Add the target locale(s); mark machine drafts; get them reviewed.
  5. Test: a pseudo-locale (accented and 40% longer), a missing-key check in CI, an RTL screenshot if in scope, and a date/number/currency snapshot per locale.

Workflow — docs

  1. Pick the doc type: README or ADR (references/docs-and-adr.md); guide, reference page, long-form manual or changelog entry (references/guides-and-reference-pages.md).
  2. Write for a reader who arrives cold: what it is, how to run it, how to check it works, where to get help.
  3. Run every command and example; fix the docs or the code until they match.
  4. For an ADR: number it, use the template, link it from the index and set its status.
  5. One owner per fact: when a fact already lives in another doc, link to it instead of copying it.
  6. For prose-heavy pages (guide introductions, a manual's summary), run humanizer in embedded mode as the last pass; it changes prose only and leaves code, commands and paths alone.

Domain gates

  • Zero hard-coded user-visible strings in the touched code (a grep or lint rule proves it); no missing keys in any shipped locale.
  • Plurals and formatted values verified in each locale (for example NL 1 resultaat / 2 resultaten).
  • A pseudo-locale run shows no clipped or overflowing text on the main screens.
  • Every README command was executed in this run, with its output or exit code recorded.
  • Each ADR has context, decision, consequences and status, and appears in the index.
  • A guide solves one problem in two to four steps, and every step shows observable proof that was really run.
  • A long-form manual labels every rationale it could not source as "inferred"; it contains no invented benchmark or guarantee.
  • A changelog entry is a draft for review; no tag or release is pushed (owner action).

Safety and honesty

  • Say which locales a human reviewed and which are machine drafts.
  • Shared gates for every playbook (honesty, owner approval, secrets, reviews): .claude/docs/forge-reference/playbook-template.md.

References

  • references/i18n.md — catalogs, key naming, ICU examples, Intl formatting, routing, RTL, pseudo-locale.
  • references/docs-and-adr.md — README and API-doc checklists, changelog rules, ADR template, index, lifecycle.
  • references/guides-and-reference-pages.md — the guide arc and step loop, the reference-page shape, the ten-section manual, the changelog flow from a commit range, one owner per fact and the delete zone.

Provenance

Core rules: Forge-native, following the public ICU MessageFormat, CLDR, W3C internationalization and MDN logical-properties documentation and the Nygard ADR format; nothing copied. The SA-W1-B2 graft was fetched read-only with gh api at the pinned commits and treated as untrusted data; it lives in references/guides-and-reference-pages.md, where the full attribution notices are kept.

Source Path Pinned SHA License Taken Excluded
vercel/next.js .agents/skills/write-guide/SKILL.md 6100e81e314f7aad0c94e189bbae87820d7efb37 MIT guide arc, six-part step loop, guide rules Next.js template, tsx examples, doc links, frontmatter keys
reactjs/react.dev .claude/skills/docs-writer-reference/SKILL.md 2e6dca162985d438d7a834b339d89177cf0a92b9 CC-BY-4.0 (attribution kept in the reference file) reference-page shape, include/exclude rules all React and MDX specifics (Hooks, RSC, Compiler, ESLint, components, heading ids)
sickn33/agentic-awesome-skills skills/docs-architect/SKILL.md 48de968b4615c294de601f72268aa7be88dde863 MIT ten-section manual outline, inferred-rationale honesty rule generic boilerplate, persona, page-count target
sickn33/agentic-awesome-skills skills/changelog-entry/SKILL.md 48de968b4615c294de601f72268aa7be88dde863 MIT range, noise filter, classification, untrusted commit text cross-skill references, tool list
affaan-m/ECC living-docs-governance not in the pinned catalog n/a MIT idea only: one owner per fact, delete zone all text; ECC docs-governance and its audit-docs.py skipped