Translate the docs
English in docs/ 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
node website/translate/translate.mjs prepare --json(add--locale esfor one locale). For each locale it prints:language: the language to write, andglossary: the terms file to follow.pages: eachsourcepage to translate into itstranslationfile.newpages need a full translation.updatepages already have one: when adiffcommand 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 adiff, 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. Eachidis<json file>#<key>; translate themessageof that key in the file.previousis its translation of older English, to update.
- Translate, following the rules below. Write each page to its
translationpath; create folders as needed. - 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 inwebsite/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>. - 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.
- 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. - Run the procedure above for every locale. If
preparelists no pages, no UI strings and nothing removed, stop without a PR. - Run
node --test website/translate/mdx.test.mjsandnode website/translate/translate.mjs check, then open a PR titleddocs(i18n): Update translationslisting 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/ folders yourself.
Translation rules
The docs 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 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,:::tipand 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.


