doc-smith-localize

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 翻译图片文字
• 翻译后将图片同步到 dist/assets/{key}/images/ 发布目录
• 翻译后更新图片 .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
• 此步骤是语言切换功能生效的关键，绝不能跳过