doc-smith-localize

# Doc-Smith 文档翻译 将文档翻译成多种语言，支持批量翻译和术语一致性。 ## 用法 ```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 # 跳过图片翻译 ``` ## 选项 | 选项 | 别名 | 说明 | |------|------|------| | `--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 重建： ```bash 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 前： 1. `rm -rf .aigne/doc-smith/cache/task-status && mkdir -p .aigne/doc-smith/cache/task-status`（重建目录，清空旧状态） #### 分发阶段 每个 Task 使用 `run_in_background: true` 分发。批次内所有 Task 同时启动。 #### 等待阶段 每 15 秒检查 `.status` 文件数量： ```bash find .aigne/doc-smith/cache/task-status -name '*.status' | wc -l ``` - 文件数 = 当前批次任务数 → 该批次完成 - 超时：单批最多等待 10 分钟，超时后报告缺失文档 - **不要读取后台 Task 的 output_file**（可能 300K+），只读 `.status` 文件 #### 收集结果 ```bash find .aigne/doc-smith/cache/task-status -name '*.status' -exec cat {} + ``` 每个文件 1 行，所有翻译摘要汇总后通常不超过 20 行。 #### 失败处理 - `.status` 内容以"失败"开头 → 记录失败原因，不阻塞后续批次 - 超时未产生 `.status` → 标记为超时，在最终报告中提示用户重试 ### 图片后端预检测 **在翻译图片之前**，主 agent 执行一次图片后端检测。检测逻辑与 `doc-smith-images` 的「后端检测」部分相同： 1. 检查 `GEMINI_API_KEY` 是否已设置 → 选定 `gemini-sdk` 2. 否则检查 AFS CLI 是否可用 → 选定 `afs-cli` 3. 均不可用 → **必须使用 AskUserQuestion 让用户选择**（配置 API Key / 安装 AFS CLI / 跳过图片翻译），禁止自动默认为 skip 检测结果记为 `{IMAGE_BACKEND}`，后续所有图片翻译调用统一使用 `--backend {IMAGE_BACKEND}`。只有用户明确选择跳过时才可设为 `skip`。 ### 翻译图片 ```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} \ --backend {IMAGE_BACKEND} ``` ### 同步图片到 dist 翻译后的图片保存在 assets 源目录，需同步到 dist 发布目录： ```bash cp .aigne/doc-smith/assets/{key}/images/{target}.png \ .aigne/doc-smith/dist/assets/{key}/images/{target}.png ``` ### 更新图片引用 翻译后 HTML 中的图片路径需更新语言后缀： - 匹配 `images/{source}.png` → 替换为 `images/{target}.png`（仅当目标语言图片存在时） ### AI 巡检 翻译和 nav.js 重建完成后，读取 `dist/` 中生成的 HTML 文件（每种语言各抽查 1-2 个页面），检查输出是否符合预期。如有问题直接修改 HTML 文件修复。 ### 翻译报告 返回翻译结果摘要，包含文档和图片的翻译/跳过/失败统计。 ## 错误处理 - Workspace 不存在：提示先使用 `/doc-smith` 生成文档 - 目标语言与源语言相同：提示指定不同的语言 - 文档路径无效：列出有效路径供用户参考 - 翻译部分失败：报告失败文档，建议使用 `--path` 单独重试 --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/aigne-io) — claim your Tome and manage your conversions. <!-- tomevault:4.0:skill_md:2026-04-13 -->