Translate Docs

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.