Translate Docs

Run this workflow from the repository root. Translate prose directly; the bundled scripts discover source/target pairs, record source fingerprints, and check the mechanical invariants.

1. Discover the batch

Synchronize the generated contributing copy first, so Step 3's CONTRIBUTING.md translation always reads current content rather than a stale or absent file:

set -euo pipefail
cd website
pnpm sync-contributing
cd ..
node .claude/skills/translate-docs/scripts/translation-lock.mjs status

Treat every reported item as one batch:

• missing: create the reported target from the complete source.
• stale: align the existing target with the current source. Targets are often hand-maintained alongside their sources, so a stale fingerprint can mean anything from one changed sentence to a rewritten page; compare the two section by section, keep wording that is still faithful, and rewrite what has drifted.
• frontmatter: make the target's untranslated frontmatter match the source (see Step 3).
• orphan: delete the reported target if it exists; the later record command removes the obsolete lock entry.

Finish discovery only after every item has an explicit action. The lockfile changes only through record.

For a large batch, dispatch subagents by file group. Give each one its exact source → target pairs and point it at Steps 2 and 3 of this file.

2. Load terminology

Before translating prose, search these truth sources for established English product terms:

• Frontend English locale: frontend/src/i18n/en/
• README.en.md

These sources are the glossary; reuse their exact terminology, including UI labels quoted in prose.

When those sources conflict, use the official name a reader outside China would recognize for the same product, not the name of a different product. Documentation translates 阿里百炼 as DashScope, matching README.en.md's established usage; the frontend locale's per-endpoint Alibaba Model Studio labels do not govern documentation.

Product identity itself is invariant across target languages. Translate 剪映 as Jianying: CapCut is a separate international product, and ArcReel has not verified draft compatibility with it. CapCut appears only where a page states that distinction.

3. Translate every dirty source

Translate natural-language prose and link text into clear technical English. Preserve the document's information, tone, section order, lists, tables, and formatting.

Apply these invariants to every file:

• In frontmatter, translate only values of title, description, and sidebar_label. Copy every other key and value from the source exactly; status reports a frontmatter item and record refuses to run until they match.
• Preserve inline code exactly.
• Inside fenced code blocks, preserve the executable substance exactly: commands, program output, identifiers, configuration keys, and paths or filenames that other software really produces. Translate the human-readable text a reader is meant to read: diagram node labels, comments, instructional placeholder values, and fences that hold prose rather than code. A literal repository convention written in Chinese stays in Chinese — Chinese commit-message examples, changelog section names, and placeholders such as <中文理由> describe what a contributor must actually type.
• Translate human-readable link text. Point each link destination at its English counterpart when one exists; otherwise keep the destination exactly:
  • A heading inside the same document: link to the target document's own heading. README.md has no explicit anchor IDs, so README.en.md links to the English heading slug — #快速开始 becomes #quick-start.
  • The documentation site: the default locale is unprefixed, so every docs.arc-reel.com/... destination gains an /en/ prefix (https://docs.arc-reel.com/guide/... becomes https://docs.arc-reel.com/en/guide/...).
  • An external page with an English edition: link to that edition, such as a repository's README.en.md in place of its #readme.
• Preserve ::: admonition marker lines exactly. Translate prose inside the admonition.
• Preserve explicit anchor IDs such as {#deployment} exactly. Translate their headings.
• Keep product names, command names, paths, configuration keys, environment variables, identifiers, and version constraints unchanged.

The lock pipeline currently registers English targets only: targetForSource in translation-lock.mjs maps every source into website/i18n/en/. Before adding another documentation locale, extend that forward mapping first — otherwise every file of the new locale is reported as an unregistered orphan and record refuses to run.

README.md maps to README.en.md. CONTRIBUTING.md maps to website/i18n/en/docusaurus-plugin-content-docs/current/dev/contributing.md; base that target on the synchronized website/docs/dev/contributing.md so its generated frontmatter and {#contributing} anchor remain intact. The lockfile records CONTRIBUTING.md as the source key but fingerprints that synchronized copy's content, not the root file's, so a sync-contributing.mjs change alone can also mark the target stale. Other Markdown sources use the exact targets printed by status.

Finish this step only when every orphan target is gone and every missing or stale target is a complete English rendering: each source section has its counterpart in the target, and the target holds nothing the source lacks.

4. Refresh UI translations

Generate the current Docusaurus message inventory, then check it:

set -euo pipefail
cd website
pnpm write-translations --locale en
cd ..
node .claude/skills/translate-docs/scripts/ui-messages.mjs

ui-messages.mjs removes the generated footer copyright key and lists every English message value still carrying Chinese text. Translate each listed message in place, preserving JSON keys, description values, and placeholders such as {count} exactly. Finish when the script prints UI messages are translated.

5. Record and verify

After all translations are complete, record LF-normalized SHA-256 fingerprints and verify the batch is clean:

set -euo pipefail
node .claude/skills/translate-docs/scripts/translation-lock.mjs record
node .claude/skills/translate-docs/scripts/translation-lock.mjs status
cd website
pnpm typecheck
pnpm build

record refuses to update the lockfile while a target is missing, while a target's untranslated frontmatter differs from its source, and while any Markdown file under website/i18n/*/docusaurus-plugin-content-docs/current/ has no source mapping to it. Completion requires status to print Translations are up to date., typecheck to pass, and the build to emit both build/ and build/en/ without broken links or anchors.