doc-smith-localize

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Doc-Smith 文档翻译

Doc-Smith Document Translation

将文档翻译成多种语言，支持批量翻译和术语一致性。

Translate documents into multiple languages, supporting batch translation and terminology consistency.

用法

Usage

bash

/doc-smith-localize --lang en                    # 翻译所有文档到英文
/doc-smith-localize -l en -l ja                  # 翻译到多个语言
/doc-smith-localize -l en -p /overview           # 只翻译指定文档
/doc-smith-localize -l en --force                # 强制重新翻译
/doc-smith-localize -l en --skip-images          # 跳过图片翻译

bash

/doc-smith-localize --lang en                    # Translate all documents to English
/doc-smith-localize -l en -l ja                  # Translate to multiple languages
/doc-smith-localize -l en -p /overview           # Translate only the specified document
/doc-smith-localize -l en --force                # Force re-translation
/doc-smith-localize -l en --skip-images          # Skip image translation

选项

Options

选项	别名	说明
`--lang <code>`	`-l`	目标语言代码（可多次使用）
`--path <docPath>`	`-p`	指定文档路径（可多次使用）
`--force`	`-f`	强制重新翻译，覆盖已有
`--skip-images`		跳过图片翻译

Option	Alias	Description
`--lang <code>`	`-l`	Target language code (can be used multiple times)
`--path <docPath>`	`-p`	Specify document path (can be used multiple times)
`--force`	`-f`	Force re-translation, overwrite existing translations
`--skip-images`		Skip image translation

约束

Constraints

以下约束在任何操作中都必须满足。

The following constraints must be satisfied in all operations.

1. Workspace 约束

1. Workspace Constraints

.aigne/doc-smith/config.yaml

和

planning/document-structure.yaml

必须存在

不存在时提示用户先使用
```
/doc-smith
```
生成文档

.aigne/doc-smith/config.yaml

and

planning/document-structure.yaml

must exist

If they do not exist, prompt the user to generate documents using
```
/doc-smith
```
first

2. 参数验证约束

2. Parameter Validation Constraints

目标语言不能与源语言（config.yaml 的 locale）相同
```
--path
```
指定的路径必须存在于 document-structure.yaml
过滤后无有效语言时报错

Target language cannot be the same as the source language (locale in config.yaml)
The path specified by
```
--path
```
must exist in document-structure.yaml
Throw an error if no valid languages are left after filtering

3. 增量翻译约束

3. Incremental Translation Constraints

基于源 HTML 的 SHA256 hash（sourceHash）判断是否需要翻译
hash 未变化的文档自动跳过（除非
```
--force
```
）
翻译失败时不覆盖已有翻译、不修改 .meta.yaml

Determine whether translation is needed based on the SHA256 hash (sourceHash) of the source HTML
Automatically skip documents where the hash has not changed (unless
```
--force
```
is used)
Do not overwrite existing translations or modify .meta.yaml if translation fails

4. Task 分发约束

4. Task Distribution Constraints

每个文档到每种语言为一个独立翻译任务
通过 Task(references/translate-document.md) 分发，并行执行
每批最多并行 5 个 Task，超过时分批执行
如有术语表（
```
.aigne/doc-smith/glossary.yaml
```
或
```
.md
```
），传递给每个 Task

Each document to each language is an independent translation task
Distribute via Task(references/translate-document.md), execute in parallel
Max 5 parallel Tasks per batch, split into batches if exceeded
If a glossary exists (
```
.aigne/doc-smith/glossary.yaml
```
or
```
.md
```
), pass it to each Task

5. 图片翻译约束

5. Image Translation Constraints

未指定
```
--skip-images
```
时，扫描 assets 中的图片资源
跳过条件（满足任一）：
```
generation.shared: true
```
、目标语言已存在、源语言图片不存在
使用
```
/doc-smith-images --update
```
翻译图片文字
翻译后更新图片 .meta.yaml 的 languages 和 translations

If
```
--skip-images
```
is not specified, scan image resources in assets
Skip conditions (meet any):
```
generation.shared: true
```
, target language already exists, source language image does not exist
Use
```
/doc-smith-images --update
```
to translate text in images
Update the languages and translations fields in the image's .meta.yaml after translation

6. Config 更新约束

6. Config Update Constraints

翻译完成后，将目标语言添加到 config.yaml 的
```
translateLanguages
```
数组
避免重复添加已存在的语言
更新后验证 config.yaml 正确

After translation is completed, add the target language to the
```
translateLanguages
```
array in config.yaml
Avoid adding existing languages repeatedly
Verify that config.yaml is correct after update

7. nav.js 重建约束

7. nav.js Rebuild Constraints

Config 更新后必须执行 nav.js 重建：

bash

node skills/doc-smith-build/scripts/build.mjs \
  --nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist

验证
```
dist/assets/nav.js
```
包含所有目标语言的 code
此步骤是语言切换功能生效的关键，绝不能跳过

Must rebuild nav.js after Config update:

bash

node skills/doc-smith-build/scripts/build.mjs \
  --nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist

Verify that
```
dist/assets/nav.js
```
contains the codes of all target languages
This step is critical for the language switch function to take effect and must not be skipped

HTML-to-HTML 翻译模型

HTML-to-HTML Translation Model

翻译直接在 HTML 层面完成，不经过 MD 中间步骤：

源 HTML → 提取可翻译区域 → 翻译 → 组装目标 HTML → 保存
dist/{source}/docs/{path}.html → dist/{target}/docs/{path}.html

可翻译区域（4 个）：

```
<title>
```
标签内文本
```
<meta name="description">
```
的 content 属性
```
<main data-ds="content">
```
标签内 HTML
```
<nav data-ds="toc">
```
标签内 HTML

不翻译：head 资源引用、script、header/footer/sidebar、HTML 属性、代码块中的代码

Translation is done directly at the HTML level without going through an MD intermediate step:

Source HTML → Extract translatable regions → Translate → Assemble target HTML → Save
dist/{source}/docs/{path}.html → dist/{target}/docs/{path}.html

Translatable regions (4 types):

Text inside
```
<title>
```
tag
content attribute of
```
<meta name="description">
```
HTML inside
```
<main data-ds="content">
```
tag
HTML inside
```
<nav data-ds="toc">
```
tag

Not translated: head resource references, scripts, header/footer/sidebar, HTML attributes, code within code blocks

翻译质量要求

Translation Quality Requirements

术语一致性：使用术语表保持专业术语统一
HTML 结构保持：标签原样保留，只翻译文本内容
上下文理解：根据技术文档语境选择合适译法
自然流畅：翻译结果符合目标语言习惯

Terminology consistency: Use glossaries to maintain unified professional terms
HTML structure preservation: Keep tags intact, only translate text content
Context understanding: Choose appropriate translations based on the technical document context
Natural fluency: Translation results conform to the target language's usage habits

关键流程

Key Processes

并行翻译文档

Parallel Document Translation

按 references/translate-document.md 流程使用单独的 Task tool 并行翻译以下文档：
- docPath=/overview, targetLanguage=en, sourceLanguage=zh, force=false
- docPath=/api/auth, targetLanguage=en, sourceLanguage=zh, force=false

Use separate Task tools to translate the following documents in parallel according to the references/translate-document.md process:
- docPath=/overview, targetLanguage=en, sourceLanguage=zh, force=false
- docPath=/api/auth, targetLanguage=en, sourceLanguage=zh, force=false

翻译图片

Image Translation

bash

/doc-smith-images "将图片中的文字从 {source} 翻译成 {target}，保持布局和风格不变" \
  --update .aigne/doc-smith/assets/{key}/images/{source}.png \
  --savePath .aigne/doc-smith/assets/{key}/images/{target}.png \
  --locale {target}

bash

/doc-smith-images "Translate text in images from {source} to {target}, keeping layout and style unchanged" \
  --update .aigne/doc-smith/assets/{key}/images/{source}.png \
  --savePath .aigne/doc-smith/assets/{key}/images/{target}.png \
  --locale {target}

更新图片引用

Update Image References

翻译后 HTML 中的图片路径需更新语言后缀：

匹配
```
images/{source}.png
```
→ 替换为
```
images/{target}.png
```
（仅当目标语言图片存在时）

After translation, update the image paths in HTML with the language suffix:

Match
```
images/{source}.png
```
→ replace with
```
images/{target}.png
```
(only if the target language image exists)

AI 巡检

AI Inspection

翻译和 nav.js 重建完成后，读取

dist/

中生成的 HTML 文件（每种语言各抽查 1-2 个页面），检查输出是否符合预期。如有问题直接修改 HTML 文件修复。

After translation and nav.js rebuild, read the generated HTML files in

dist/

(spot-check 1-2 pages per language) to verify if the output meets expectations. Directly modify the HTML files to fix any issues found.

翻译报告

Translation Report

返回翻译结果摘要，包含文档和图片的翻译/跳过/失败统计。

Return a summary of translation results, including statistics on translated/skipped/failed documents and images.

错误处理

Error Handling

Workspace 不存在：提示先使用
```
/doc-smith
```
生成文档
目标语言与源语言相同：提示指定不同的语言
文档路径无效：列出有效路径供用户参考
翻译部分失败：报告失败文档，建议使用
```
--path
```
单独重试

Workspace does not exist: Prompt the user to generate documents using
```
/doc-smith
```
first
Target language is the same as source language: Prompt to specify a different language
Invalid document path: List valid paths for user reference
Partial translation failure: Report failed documents, suggest retrying individually with
```
--path
```