translate-docs

---
name: translate-docs
description: Translate documentation (.md files) into another language. Use when: translating a markdown doc, updating an existing translation after source changes, localizing documentation, creating a french translation of a doc, keeping translations in sync with the source. Default target language is French. Translated files are placed in a folder named after the language (e.g. 'french/') mirroring the source path.
license: MIT
---

# translate-docs

Translates `.md` documentation files into a target language and places them in a language-named folder that mirrors the source path structure.

## When to Use

- Translating a new `.md` doc into French (or another language)
- Updating a translation when the source `.md` has changed
- Checking whether an existing translation is up to date

## Conventions

| Concept | Convention |
|---|---|
| Target language folder | Named after the language in lowercase English (e.g. `french/`, `spanish/`, `german/`) |
| Output path | Insert the language folder under the source folder path (e.g. `docs/foo.md` → `docs/french/foo.md`) |
| File name | Same as the source file name |
| Default language | **French** (use when no language is specified) |

## Procedure

### Step 1 — Identify source and output paths

1. Note the source `.md` path (e.g. `docs/acquisition-node-comparison.md`).
2. Determine the target language (default: `french`).
3. Compute the output path: insert the language folder inside the source file’s parent folder.
   - Example: `docs/foo.md` → `docs/french/foo.md`
   - Example: `readme.md` → `french/readme.md` (root files place `french` in workspace root)

### Step 2 — Check for an existing translation

- If the output file **does not exist**: proceed to Step 3 (full translation).
- If the output file **exists**: proceed to Step 4 (incremental update).

### Step 3 — Full translation (new file)

1. Read the entire source `.md` file.
2. Translate all prose content into the target language.
3. **Preserve exactly**:
   - Markdown structure (headings, lists, tables, code blocks, links, images)
   - Code snippets and inline code (do **not** translate code)
   - Technical terms, product names, API names, and proper nouns
   - Front-matter YAML/TOML (translate values only if they are human-readable descriptions)
   - Link URLs (translate only visible link text if appropriate)
4. Create the output file at the computed path (create parent directories if needed).

### Step 4 — Incremental update (existing translation)

1. Read both the source `.md` and the existing translation.
2. Identify sections or paragraphs that differ between the current source and what the translation reflects.
   - Use structural landmarks (headings, table rows) to align the two documents.
3. Translate only the changed or added content.
4. Preserve already-correct translated sections unchanged.
5. Overwrite the translation file with the updated content.

### Step 5 — Quality check

After writing the output file, verify:
- [ ] All headings are translated.
- [ ] No source-language sentences remain (except inside code blocks).
- [ ] Code blocks are untouched.
- [ ] Table structure is intact.
- [ ] Internal links still resolve (adjust relative paths if the folder depth changed).
- [ ] File saved at the correct output path.

## Examples

| User prompt | Source | Output |
|---|---|---|
| "Translate docs/foo.md" | `docs/foo.md` | `docs/french/foo.md` |
| "Translate readme.md to spanish" | `readme.md` | `french/readme.md` |
| "Update the french translation of docs/bar.md" | `docs/bar.md` | `docs/french/bar.md` (updated) |