translate

---
name: translate
description: Translate documentation pages to all missing locales. Use when a document exists in one locale but needs to be translated to others. Supports --dry-run, single-locale targeting, and incremental updates.
license: MPL-2.0
---

# Translate Documentation

Translate the document at the given target path to locales that are missing or outdated.

## Argument Parsing

Parse `$ARGUMENTS` into these parts:

- **target**: The first positional argument — a document path (e.g. `wonder-mesh`, `billing/plans.mdx`, `en-US/wonder-mesh`)
- **locale filter** (optional): If a second positional argument matches a known locale (`zh-TW`, `zh-CN`, `ja-JP`, `es-ES`), translate to **only** that locale instead of all missing locales
- **--dry-run** flag (optional): If present anywhere in the arguments, only print the detection summary — do NOT write any files

Examples:
- `/translate wonder-mesh` → translate to all missing locales
- `/translate wonder-mesh zh-TW` → translate to zh-TW only
- `/translate wonder-mesh --dry-run` → detection report only
- `/translate wonder-mesh zh-TW --dry-run` → detection report for zh-TW only

## Context

This is a **Nextra-based** documentation site with these locales:
- `en-US` (English — primary/source locale)
- `zh-TW` (Traditional Chinese)
- `zh-CN` (Simplified Chinese)
- `ja-JP` (Japanese)
- `es-ES` (Spanish)

All docs live under `pages/<locale>/`. Each section has a `_meta.ts` file for navigation labels (these must also be translated).

### Glossary

Before translating, read the glossary file at `${CLAUDE_SKILL_DIR}/glossary.json`. This file maps English terms to their approved translations per locale. When translating:
- Terms marked `"keep": true` must remain in English (brand names, technical acronyms)
- Terms with locale-specific values must use the exact translation provided (e.g. "server" → "伺服器" in zh-TW, "服务器" in zh-CN)
- This ensures terminology consistency across the entire documentation site

### Dashboard UI Term Translations

When translating text that references **platform UI elements** (button labels, tab names, menu items, dialog titles), use the `/i18n-lookup` skill to find the exact translations from the Zeabur dashboard's i18n files. The dashboard i18n source is located at `../../dashboard/public/assets/locales/{locale}/`.

**Why this matters**: Users reading docs in their language should see the same UI terms they see in the dashboard. For example, the "Networking" tab should appear as "網路" in zh-TW docs because that's what the dashboard displays.

If the dashboard i18n files are not available (the path does not exist), fall back to the glossary and contextual translation.

## Instructions

### Phase 1: Detect Missing & Outdated Translations

1. **Determine the source locale** — identify which locale(s) already have the target. If the target path includes a locale prefix (e.g. `en-US/wonder-mesh`), use that. If it's just a relative path (e.g. `wonder-mesh/get-started.mdx`), search all locales to find the source. Prefer `en-US` as the source if it exists there.

2. **List all files** under the source path. For example, if the target is `wonder-mesh`, list all `.mdx` files and `_meta.ts` files under `pages/<source-locale>/wonder-mesh/`.

3. **Determine target locales** — if a locale filter was provided, only check that locale. Otherwise, check all 4 non-source locales.

4. For each target locale, check which files are **missing or outdated**:
   - **Missing**: The file does not exist at all
   - **Outdated (stub)**: The file exists but is significantly shorter than the source (likely a stub/placeholder)
   - **Outdated (stale)**: The file exists but the source file has been modified more recently. Use `git log -1 --format="%H %ai" -- <file>` to compare the last commit date of the source file vs the translated file. If the source file's last commit is **newer** than the translation's last commit, mark it as stale.

5. **Print a summary table** showing:
   - Each target locale
   - Each file and its status: `missing`, `outdated (stub)`, `outdated (stale)`, or `up-to-date`
   - Total files needing action per locale

6. **If `--dry-run` is set**: Stop here. Print the summary and exit. Do NOT proceed to Phase 2.

7. **If no files need action**: Print "All translations are up to date." and exit.

### Phase 2: Parallel Translation

**Spawn one agent per target locale** that needs translation. All translation agents run in parallel.

Each translation agent must:

1. **Read the glossary** at `${CLAUDE_SKILL_DIR}/glossary.json` and use it throughout translation.
2. **Look up dashboard UI translations** — scan the source file for UI element references (bold text like `**Button Label**`, quoted UI text like `"Tab Name"` or `「Menu Item」`). For each one, first search the `en-US` dashboard i18n files at `../../dashboard/public/assets/locales/en-US/` to find the i18n key for the English term, then look up that key in the target locale's files at `../../dashboard/public/assets/locales/{target-locale}/`. Check relevant JSON files (`common.json`, `service.json`, `servers.json`, `project.json`). If the dashboard i18n path does not exist, skip this step silently and rely on the glossary and contextual translation.
3. **Read the source file(s)** in full.
4. **Read the corresponding `_meta.ts`** in the source locale for navigation labels.
5. **If the file is `outdated (stale)`** (not missing):
   - Read the existing translation file
   - Use `git diff <old-commit>..<new-commit> -- <source-file>` to see what changed in the source
   - Update only the sections that changed, preserving the rest of the existing translation
   - This is more efficient and preserves any manual translation adjustments
6. **If the file is `missing` or `outdated (stub)`**: Translate the full source file.
7. **Translate all content** into the target language:
   - Translate all prose, headings, callouts, and UI text
   - Consult the glossary for all terminology — use the exact translations specified
   - For **UI element references** (button labels, tab names, menu items rendered in bold or quotes), use the translations found in step 2 from the dashboard i18n files. These take precedence over the glossary for UI-specific terms, since they reflect what users actually see in the platform
   - Keep **all MDX imports** unchanged (e.g. `import { Callout } from 'nextra/components'`)
   - Keep **all image paths** unchanged (e.g. `![...](/wonder-mesh/install-script.png)`)
   - Keep **all URLs/links** unchanged unless they are locale-specific documentation links
   - Keep **code blocks** unchanged (only translate comments inside code blocks if they are user-facing)
   - Keep **frontmatter keys** unchanged (`title`, `ogImageTitle`, `ogImageSubtitle`) but translate their **values**
   - For `_meta.ts`: translate the display labels but keep the keys unchanged
   - Preserve the original file structure and formatting exactly
8. **Write the translated files** to the correct locale directory.
9. If the locale's **parent `_meta.ts`** does not have an entry for this section, add it with the translated label (consulting the glossary for the label).

### Translation Quality Guidelines

- Use **natural, idiomatic** phrasing for each language — do not produce literal word-for-word translations
- For `zh-TW`: use Traditional Chinese characters (繁體中文), not Simplified
- For `zh-CN`: use Simplified Chinese characters (简体中文)
- For `ja-JP`: use standard Japanese with appropriate kanji/hiragana/katakana mix
- For `es-ES`: use Castilian Spanish conventions
- Always consult the glossary — terms marked `"keep": true` stay in English, others use the specified translation
- When a term is not in the glossary but is a well-known technical term, keep it in English

### Phase 3: Verification (Main Agent)

After all translation agents complete, the main agent must:

1. **Verify file existence**: Glob for all expected files across all target locales and confirm they exist.
2. **Verify `_meta.ts` consistency**: Read each target locale's `_meta.ts` and confirm the section entry is present with a translated label.
3. **Spot-check content quality**: Read the first 20 lines of each translated file to verify:
   - Frontmatter is properly translated
   - MDX imports are preserved
   - Image paths are unchanged
   - The content is in the correct language
   - Glossary terms are used correctly
4. **Verify structural consistency**: Ensure every target locale has the same number of files for the target section.
5. **Print a final summary**:
   - Number of files created/updated per locale
   - Translation mode used per file (full translation vs incremental update)
   - Any issues found
   - Confirmation that all target locales are complete