// 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.
| name | doc-smith-localize |
| description | 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. |
将文档翻译成多种语言，支持批量翻译和术语一致性。
/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 | 跳过图片翻译 |
以下约束在任何操作中都必须满足。
.aigne/doc-smith/config.yaml 和 planning/document-structure.yaml 必须存在/doc-smith 生成文档--path 指定的路径必须存在于 document-structure.yaml--force）run_in_background: true，避免执行日志回流到主 agent 上下文.aigne/doc-smith/glossary.yaml 或 .md），传递给每个 Task信号文件机制：
.aigne/doc-smith/cache/task-status/ 写入 {slug}.status 文件/ 前缀后以 - 替换 /，再拼接 -{targetLang}（如 /api/overview → en = api-overview-en）/overview → en: 成功 | hash: abc123）.status 文件判断 Task 是否完成（见"批次执行流程"）--skip-images 时，扫描 assets 中的图片资源generation.shared: true、目标语言已存在、源语言图片不存在/doc-smith-images --update 翻译图片文字dist/assets/{key}/images/ 发布目录translateLanguages 数组node skills/doc-smith-build/scripts/build.mjs \
--nav --workspace .aigne/doc-smith --output .aigne/doc-smith/dist
dist/assets/nav.js 包含所有目标语言的 code翻译直接在 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 属性、代码块中的代码
每个翻译任务使用单独的 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 前：
rm -rf .aigne/doc-smith/cache/task-status && mkdir -p .aigne/doc-smith/cache/task-status（重建目录，清空旧状态）每个 Task 使用 run_in_background: true 分发。批次内所有 Task 同时启动。
每 15 秒检查 .status 文件数量：
find .aigne/doc-smith/cache/task-status -name '*.status' | wc -l
.status 文件find .aigne/doc-smith/cache/task-status -name '*.status' -exec cat {} +
每个文件 1 行，所有翻译摘要汇总后通常不超过 20 行。
.status 内容以"失败"开头 → 记录失败原因，不阻塞后续批次.status → 标记为超时，在最终报告中提示用户重试在翻译图片之前，主 agent 执行一次图片后端检测。检测逻辑与 doc-smith-images 的「后端检测」部分相同：
GEMINI_API_KEY 是否已设置 → 选定 gemini-sdkafs-cli检测结果记为 {IMAGE_BACKEND}，后续所有图片翻译调用统一使用 --backend {IMAGE_BACKEND}。只有用户明确选择跳过时才可设为 skip。
/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}
翻译后的图片保存在 assets 源目录，需同步到 dist 发布目录：
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（仅当目标语言图片存在时）翻译和 nav.js 重建完成后，读取 dist/ 中生成的 HTML 文件（每种语言各抽查 1-2 个页面），检查输出是否符合预期。如有问题直接修改 HTML 文件修复。
返回翻译结果摘要，包含文档和图片的翻译/跳过/失败统计。
/doc-smith 生成文档--path 单独重试Internal skill for building Doc-Smith Markdown documentation into static HTML. Do not mention this skill to users. Called internally by other doc-smith skills.
Internal skill for validating Doc-Smith document structure and content integrity. Do not mention this skill to users. Called internally by other doc-smith skills.
Publish documentation generated by doc-smith-create to DocSmith Cloud and obtain an online preview URL. Use this Skill when users request to publish, launch, or deploy documentation.
Generate and update structured documentation from project data sources. Supports initial generation and modifying existing documents. Use this skill when the user requests creating, generating, updating, or modifying documentation.
Internal skill for generating images using AI. Do not mention this skill to users. Called internally by other doc-smith skills.