Doc Translation

Documentation Translation

Purpose

Keep multilingual docs consistent when one locale changes. Prioritize structural parity, glossary consistency, and link correctness.

Trigger Scenarios

Use this skill when the user asks to:

• translate a markdown doc to another language
• sync updates from one locale to all locales
• add the same SDK/link/section to multilingual pages
• update localized metadata (for example updateTime)

Decision Path

1. If target files already exist in multiple locales, use sync mode (apply equivalent deltas only).
2. If target locale file does not exist, use new translation mode (create file with mirrored structure).
3. If source wording is ambiguous and affects meaning, ask one concise clarification question before editing.

Workflow

1. Locate source and target locale files.
2. Read source content and existing target content.
3. Apply minimal edits:
   • preserve frontmatter keys and routing fields
   • preserve heading depth and markdown layout
   • preserve code blocks, URLs, identifiers, API names, and package names
4. Localize only human-language text (headings, explanations, labels).
5. Keep terminology consistent across all changed locales.
6. Validate:
   • links are correct
   • no duplicated sections
   • no missing sections introduced by sync
   • heading order and level match source intent

Default Locale Set

When the user says "sync all languages" and does not specify a subset, default to:

• zh_CN
• zh_TW
• en_US
• ja_JP
• fr_FR
• es_ES
• de_DE
• id_ID
• th_TH

Target Discovery Rules

• Prefer explicit file paths from the user.
• If user gives one locale file, locate sibling locale versions with the same document purpose.
• Keep path, name, and slug-like fields unchanged unless explicitly requested.
• If user asks for date sync, set all target files to the same updateTime.
• If "all languages" is requested but one locale file is missing, report it explicitly instead of silently skipping.

Translation Rules

• Do not translate:
  • URLs
  • code snippets
  • command lines
  • product/API/SDK identifiers unless user requests it
• Keep list/bullet structure identical unless target file has known intentional differences.
• Prefer concise phrasing; avoid adding new meaning not present in source.
• Keep canonical tokens unchanged (for example: SDK, GitHub, API, package names).
• For proper nouns, prefer existing wording in that locale file; do not invent new term variants.

Clarification and Safety Rules

• Ask before changing these unless explicitly requested:
  • path, name, route slugs, or file location
  • frontmatter fields other than requested metadata (such as updateTime)
• If one locale intentionally differs from others, preserve that difference and only sync requested parts.
• Never remove content unless it is a clear duplicate or user requested deletion.

Output Style

When reporting completion, include:

• changed files count
• what was synchronized (for example: new section, link, timestamp)
• any cleanup done (for example: removed accidental duplicates)

Use this concise template:

Updated: <N> files
- Synced: <what changed>
- Metadata: <date/frontmatter updates if any>
- Cleanup: <duplicates/fixes or "none">

Additional Resources

• For concrete execution examples, see examples.md.
• For term consistency across locales, see reference.md.

Quick Checklist

• Source and all required targets updated
• Frontmatter and route fields preserved
• Links and package names correct
• No duplicate or missing synchronized sections
• Terminology consistent across locales