# Doc Translation

> Translate and synchronize documentation across locales with consistent terminology and structure. Use when the user asks to translate docs, sync one language change to other language versions, update multilingual markdown pages, or maintain i18n document parity.

- Skill: `lixr0107/doc-translation` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lixr0107/doc-translation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lixr0107/doc-translation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: lixr0107 (https://skillmd.com/u/lixr0107)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lixr0107/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:

```markdown
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](examples.md).
- For term consistency across locales, see [reference.md](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