translate-explanation

Translate Explanation

Translate generated code-explanation docs (the kind produced by the code-explanation skill) into another language. The prose is translated but everything technical stays in English so the docs remain accurate and usable by engineers.

Default language is Chinese (ZH). If the user names another language, use its code instead (see the table below).

Translation modes

First decide what's being translated — a whole folder or a single file — because the output shape differs.

Folder mode (default). The target is a CODE_EXPLANATION/ folder (or any folder of docs). Produce a parallel folder named <FOLDER>_<LANG> (e.g. CODE_EXPLANATION_ZH) with the same files. See Folder mode below.

Single-file mode. The target is one file. Choose between two output styles based on the file's length, because what's pleasant to read differs by size:

• Bilingual / interleaved (small files, < 50 lines). Update the file in place so each prose line is immediately followed by its translation — English line, then Chinese line. For short files this keeps original and translation together and is easy to scan. See Single-file mode → Bilingual.
• Sidecar file (larger files, ≥ 50 lines). Don't clutter a long file with interleaving. Instead create a fully-translated copy named <name>_<lang>.<ext> (e.g. notes_zh.md) in the same folder, leaving the original untouched. See Single-file mode → Sidecar.

Use the line count of the source file to pick the style; if the user explicitly asks for one style, honor that regardless of size.

In every mode, the rules in What to translate vs. keep as-is apply.

Folder mode

1. Locate the source folder

Find the explanation folder to translate. By default this is CODE_EXPLANATION/ at the repo root. If it isn't there, search for it (find . -type d -name 'CODE_EXPLANATION' -not -path '*/node_modules/*') and confirm with the user if there are multiple candidates. List its files so you know exactly what to translate — typically OVERVIEW.md and numbered files like 01_architecture.md, 02_models.md, etc.

2. Resolve the target language and output folder

Map the requested language to a short uppercase code and create the output folder CODE_EXPLANATION_<CODE> as a sibling of the source folder.

Language	Code	Output folder
Chinese	ZH	CODE_EXPLANATION_ZH
Spanish	ES	CODE_EXPLANATION_ES
French	FR	CODE_EXPLANATION_FR
German	DE	CODE_EXPLANATION_DE
Japanese	JA	CODE_EXPLANATION_JA
Korean	KO	CODE_EXPLANATION_KO
Hindi	HI	CODE_EXPLANATION_HI
Portuguese	PT	CODE_EXPLANATION_PT

If no language is given, default to Chinese (ZH). For a language not in the table, use its common two-letter ISO 639-1 code, uppercased.

3. Translate each file, one by one

For every file in the source folder, create a file with the exact same name in the output folder. Filenames never change — 01_architecture.md stays 01_architecture.md, not 01_架构.md. This keeps the two folders aligned side by side so a reader can compare them file-for-file.

Translate the prose into the target language while keeping everything technical in English. Read each source file, translate its content, and write the result. Don't translate by guesswork from filenames — translate the actual content.

Single-file mode

When the target is a single file (not a folder), first count its lines to choose the output style, then resolve the language code (Chinese/ZH by default).

Bilingual / interleaved (small files, < 50 lines)

Edit the file in place. After each translatable prose line, insert its translation on the next line, so the file alternates English then the target language. This keeps a short file readable as a single bilingual document.

• Leave code blocks verbatim and unduplicated — never interleave inside a fenced block; just keep it once.
• For a heading, put the original heading, then the translated heading on the next line (both as headings).
• Blank lines and structure stay intact.

Example (English file → bilingual):

# Architecture
# 架构

The handler authenticates the caller, then renders a response.
该 handler 会对调用方进行认证，然后渲染出一个 response。

Sidecar file (larger files, ≥ 50 lines)

Don't interleave a long file — it becomes hard to read. Instead create a new file in the same folder named <name>_<lang>.<ext>: take the original filename, insert _<lang> before the extension (lowercase code), e.g. design.md → design_zh.md, README.txt → README_zh.txt. Write a complete translation there following the standard rules, and leave the original file unchanged.

What to translate vs. keep as-is

The guiding idea: an engineer reading the translated docs should see their own language for the explanations, but the exact same code and terminology they'd find in the editor. Translating an identifier or a library name would make the docs wrong and unsearchable, so leave those untouched.

Translate (the prose):

• Sentences and paragraphs that explain things.
• The descriptive part of headings — but keep technical nouns in English. Example: ## Data models and validation → ## 数据模型与 validation (translate the connective prose, keep validation as the technical term).
• Table cells that contain descriptions/explanations.

Keep exactly as-is (do NOT translate):

• Filenames — same name in the output folder.
• Fenced code blocks (```…```) — copy verbatim, including any code comments. Code is code.
• Inline code in backticks — RequestHandler, pip install treecap, src/server/handler.py.
• Identifiers and symbols — class/function/variable names, module paths, file paths, line references like handler.py:42.
• Library, framework, tool, and product names — FastAPI, Pydantic, React, PostgreSQL, treecap.
• Established technical terms — keep them in English inline within the translated sentence (e.g. dependency injection, middleware, registry pattern, endpoint, schema, async). These are the shared vocabulary engineers use regardless of spoken language; translating them adds confusion, not clarity.
• URLs, commands, and config snippets.

Example (English → Chinese)

Source (01_architecture.md):

The central request handler lives in `src/server/handler.py`. Every inbound
request flows through `handle()`: it authenticates the caller, loads the
relevant record, and renders a response. Note the dependency injection in
`__init__` — `Store` and `AuthService` are passed in rather than constructed
here, which makes the handler unit-testable.

```python
async def handle(self, req: Request) -> Response:
    user = await self.auth.verify(req.token)
    return self._render(record, user)
```

Translated (01_architecture.md inside CODE_EXPLANATION_ZH/):

核心的 request handler 位于 `src/server/handler.py`。每个进入的请求都会经过
`handle()`：它会对调用方进行认证，加载相关的 record，然后渲染出 response。注意
`__init__` 中使用了 dependency injection —— `Store` 和 `AuthService` 是被传入的，
而不是在这里构造的，这使得该 handler 可以进行单元测试。

```python
async def handle(self, req: Request) -> Response:
    user = await self.auth.verify(req.token)
    return self._render(record, user)
```

Notice: the code block is byte-for-byte identical, all backticked identifiers stay English, technical terms (handler, dependency injection, record, response) stay English inline, and only the connective prose is translated.

Quick checklist

• Determined the mode: whole folder, or a single file
• Resolved target language code (Chinese/ZH by default)
• Folder mode: created <FOLDER>_<CODE>/ sibling, one output file per source file with identical filenames
• Single file < 50 lines: edited in place, bilingual (English line then translation line), code blocks kept once
• Single file ≥ 50 lines: wrote a <name>_<lang>.<ext> sidecar in the same folder, original untouched
• Prose translated; code blocks, identifiers, paths, and tool/library names verbatim
• Technical terms kept in English inline within translated sentences