Translate the docs

English in docs/ and website/blog/ is the only source. website/translate/translate.mjs lists what to translate and checks what you wrote; you do the translating. How the pieces fit: website/translate/README.md.

Procedure

1. node website/translate/translate.mjs prepare --json (add --locale es for one locale). For each locale it prints:
   • language: the language to write, and glossary: the terms file to follow.
   • pages: each source page to translate into its translation file. new pages need a full translation. update pages already have one: when a diff command is given, run it to see what changed in English and change only the matching parts of the translation, keeping every other line as it is (reviewed wording survives this way). Without a diff, compare the translation against the English yourself.
   • removed: translations it deleted because their page is no longer translated; commit the deletion.
   • ui: UI strings (navbar, footer, sidebar labels) still in English. Each id is <json file>#<key>; translate the message of that key in the file. previous is its translation of older English, to update.
2. Translate, following the rules below. Write each page to its translation path; create folders as needed.
3. Before committing, node website/translate/translate.mjs finalize. It checks every changed translation against its English, adds heading anchors, and records the English it translates in website/translate/lock/<locale>.json. Fix each ✗ problem it prints and run it again until it passes. A UI string that should read the same as English (a product name) is accepted with --same <id>.
4. Commit the translations, the UI JSON files and the lock together.

Weekly run

A Claude Code routine runs this early every Sunday morning; run by hand the same way.

1. Start from the latest master. If a translation PR from an earlier run is still open, stop: one update at a time keeps review small.
2. Run the procedure above for every locale. If prepare lists no pages, no UI strings and nothing removed, stop without a PR.
3. Run node --test website/translate/mdx.test.mjs and node website/translate/translate.mjs check, then open a PR titled docs(i18n): Update translations listing per locale the pages translated, updated and removed.

Never edit website/translate/lock/*.json or the generated website/i18n/<locale>/docusaurus-plugin-content-docs*/current/ and docusaurus-plugin-content-blog/ folders yourself.

Translation rules

The docs and blog are for Reactive Data Client (@data-client), a TypeScript library for fetching, caching and mutating async data in React and Vue apps.

Write natural, precise technical prose for developers, as a native-speaking engineer would. Keep the meaning, tone and level of detail; never add, drop or summarize content.

Pages are MDX (Markdown with JSX) for Docusaurus. Translate only human-readable prose: paragraphs, headings, list items, table cells, admonition titles (the text in :::tip[...]), link text, image alt text, text between JSX tags, label/title/alt/description/caption attribute strings, and the title, sidebar_label and description front matter values (and their react_/vue_ variants).

Keep everything else byte for byte (finalize rejects changes to it):

• Code blocks, inline code (like this), import and export lines, JSX tags and their other attributes, {expressions} and HTML.
• Directive lines: :::react, :::vue, :::tip and other ::: lines, and inline :react[...]/:vue[...] (translate only the text in their brackets).
• Link and image URLs, front matter keys and every other front matter value, and heading ids like {#some-id}.
• Markdown structure: the same headings at the same levels, paragraphs, lists, tables and blank lines.

Product, API and package names stay in English. The glossary of each language has the rest.