Skip to content

reactive/data-client / .agents/skills/translate-docs

translate-docs

Verified

Translate the docs site and blog into another language (website/i18n), or update translations after the English docs or blog changed; the repo lists the work and validates it, any model can translate

FileKindSize
SKILL.mdskill md4.5 KB
---
name: translate-docs
description: Translate the docs site and blog into another language (website/i18n), or update translations after the English docs or blog changed; the repo lists the work and validates it, any model can translate
disable-model-invocation: true
metadata:
  internal: true
---

# 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>`. A UI string listed as translating other English changed since `prepare`: run `prepare` again and translate what it lists. Don't clear it with `--same`, which is for text meant to match English.
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.

The blog's `tags.yml` and `authors.yml` are YAML, not MDX: translate only the tag `label` and `description` values and the author `title`, keeping every key, permalink and other value.

Product, API and package names stay in English. The glossary of each language has the rest.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall