Learn-skills.dev doc-smith-localize

Translate Doc-Smith generated documentation into multiple languages. Use this skill when the user requests document translation, localization, or multi-language support. Supports batch translation of documents and images.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/aigne-io/doc-smith-skills/doc-smith-localize" ~/.claude/skills/neversight-learn-skills-dev-doc-smith-localize && rm -rf "$T"

manifest: data/skills-md/aigne-io/doc-smith-skills/doc-smith-localize/SKILL.md

source content

Doc-Smith 文档翻译

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

用法

/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          # 跳过图片翻译

选项

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

约束

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

1. Workspace 约束

.aigne/doc-smith/config.yaml

和

planning/document-structure.yaml

必须存在

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

2. 参数验证约束

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

3. 增量翻译约束

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

4. Task 分发约束

每个文档到每种语言为一个独立翻译任务
通过 Task(references/translate-document.md) 分发，所有翻译 Task 必须使用
run_in_background: true
，避免执行日志回流到主 agent 上下文
每批最多并行 5 个 Task，超过时分批执行
如有术语表（
```
.aigne/doc-smith/glossary.yaml
```
或
```
.md
```
），传递给每个 Task

信号文件机制：

每个 Task 完成时在

.aigne/doc-smith/cache/task-status/

写入

{slug}.status

文件

slug 规则：docPath 去除
```
/
```
前缀后以
```
-
```
替换
```
/
```
，再拼接
```
-{targetLang}
```
（如
```
/api/overview
```
→
```
en
```
=
```
api-overview-en
```
）
状态文件内容为 1 行摘要（如
```
/overview → en: 成功 | hash: abc123
```
）
主 agent 通过轮询
```
.status
```
文件判断 Task 是否完成（见"批次执行流程"）

5. 图片翻译约束

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

6. Config 更新约束

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

7. nav.js 重建约束

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

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

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

HTML-to-HTML 翻译模型

翻译直接在 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 属性、代码块中的代码

翻译质量要求

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

关键流程

并行翻译文档

每个翻译任务使用单独的 Task tool 生成（≤ 5 个并行，> 5 个分批）。必须使用

run_in_background: true

分发 Task。必须使用以下模板构造 Task prompt：

你是文档翻译代理。请先用 Read 工具读取 {TRANSLATE_DOC_MD_PATH} 作为你的完整工作流程，然后严格按照其中的步骤执行。

你的翻译任务参数如下：
- docPath：{DOC_PATH}
- targetLanguage：{TARGET_LANG}
- sourceLanguage：{SOURCE_LANG}
- force：{FORCE}
- glossary：{GLOSSARY}
- 状态文件路径：{STATUS_FILE_PATH}

完成检查清单（必须在写入状态文件前逐项确认）：
□ 步骤 2 增量检查：已验证是否需要翻译
□ 步骤 3 提取：已提取 4 个可翻译区域
□ 步骤 4 翻译：已完成翻译并保持 HTML 结构
□ 步骤 5 组装：已保存目标语言 HTML
□ 步骤 6 Meta：已更新 .meta.yaml
□ 状态文件：已将 1 行摘要写入 {STATUS_FILE_PATH}

模板变量说明：

{TRANSLATE_DOC_MD_PATH}

：

references/translate-document.md

的绝对路径

```
{DOC_PATH}
```
：文档路径，如
```
/overview
```
```
{TARGET_LANG}
```
：目标语言代码，如
```
en
```
```
{SOURCE_LANG}
```
：源语言代码，如
```
zh
```
```
{FORCE}
```
：是否强制翻译
```
{GLOSSARY}
```
：术语表内容（如有）

{STATUS_FILE_PATH}

：

.aigne/doc-smith/cache/task-status/{slug}.status

批次执行流程

准备阶段

分发第一个 Task 前：

mkdir -p .aigne/doc-smith/cache/task-status

rm -f .aigne/doc-smith/cache/task-status/*.status

（清空旧状态）

分发阶段

每个 Task 使用

run_in_background: true

分发。批次内所有 Task 同时启动。

等待阶段

每 15 秒检查

.status

文件数量：

ls .aigne/doc-smith/cache/task-status/*.status 2>/dev/null | wc -l

文件数 = 当前批次任务数 → 该批次完成
超时：单批最多等待 10 分钟，超时后报告缺失文档
不要读取后台 Task 的 output_file（可能 300K+），只读
```
.status
```
文件

收集结果

cat .aigne/doc-smith/cache/task-status/*.status

每个文件 1 行，所有翻译摘要汇总后通常不超过 20 行。

失败处理

```
.status
```
内容以"失败"开头 → 记录失败原因，不阻塞后续批次
超时未产生
```
.status
```
→ 标记为超时，在最终报告中提示用户重试

翻译图片

/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}

更新图片引用

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

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

AI 巡检

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

dist/

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

翻译报告

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

错误处理

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