SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdoc-smith-localize

doc-smith-localize

Writing & research

View repository

Updated 10-15 19:53

About this skill

Doc-Smith Document Translation

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

Usage

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

Options

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, overwriting existing
--skip-images Skip image translation

Constraints

The following constraints must be satisfied in any operation.

1. Workspace Constraints

  • .aigne/doc-smith/config.yaml and planning/document-structure.yaml must exist
  • If not present, prompt the user to first use /doc-smith to generate the document

2. Parameter Validation Constraints

  • The target language cannot be the same as the source language (config.yaml's locale)
  • --path The specified path must exist in document-structure.yaml
  • Error out when there are no valid languages after filtering

3. Incremental Translation Constraints

  • Determine whether translation is needed based on the source HTML's SHA256 hash (sourceHash)
  • Documents with unchanged hashes are automatically skipped (unless --force）
  • On translation failure, do not overwrite existing translations and do not modify .meta.yaml

4. Task Distribution Constraints

  • Each document to each language is an independent translation task
  • Distribute through Task(references/translate-document.md),All translation Tasks must use run_in_background: true, to avoid execution logs flowing back into the main agent context
  • At most 5 Tasks in parallel per batch; execute in batches when exceeded
  • If there is a glossary (.aigne/doc-smith/glossary.yaml or .md), pass it to each Task

Signal file mechanism:

  • When each Task completes, write .aigne/doc-smith/cache/task-status/ into {slug}.status file
  • Slug rule: after removing the / prefix from docPath, replace - with /, then concatenate with -{targetLang}(e.g., /api/overview → en = api-overview-en）
  • The status file content is a 1-line summary (e.g., /overview → en: 成功 | hash: abc123）
  • The main agent polls the .status file to determine whether a Task is complete (see "Batch Execution Flow")

5. Image Translation Constraints

  • When --skip-images is not specified, scan image resources in assets
  • Skip conditions (any one satisfied):generation.shared: true, target language already exists, source language image does not exist
  • Use /doc-smith-images --update to translate text in images
  • After translation, sync images to the dist/assets/{key}/images/ publish directory
  • After translation, update the languages and translations in the image's .meta.yaml

6. Config Update Constraints

  • After translation is complete, add the target language to config.yaml's translateLanguages array
  • Avoid adding existing languages repeatedly
  • After updating, verify that config.yaml is correct

7. nav.js Rebuild Constraints

  • After Config updatemustexecute nav.js rebuild: 
    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 key to making the language switching feature work; it must never be skipped

HTML-to-HTML Translation Model

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

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

Translatable regions(4):

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

Do not translate: head resource references, script, header/footer/sidebar, HTML attributes, code in code blocks

Translation quality requirements

  • Terminology consistency: use the glossary to keep professional terminology consistent
  • HTML structure preservation: keep tags as-is, translate only the text content
  • Contextual understanding: choose appropriate translations based on the technical documentation context
  • Natural and fluent: the translation results conform to the target language's conventions

Key workflow

Translate documents in parallel

Each translation task is generated using a separate Task tool (≤ 5 in parallel, > 5 in batches).Must use run_in_background: true to dispatch Tasks. The Task prompt must be constructed using the following template:

你是文档翻译代理。请先用 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}

Template variable descriptions：

  • {TRANSLATE_DOC_MD_PATH}：references/translate-document.md the absolute path of
  • {DOC_PATH}: document path, such as /overview
  • {TARGET_LANG}: target language code, such as en
  • {SOURCE_LANG}: source language code, such as zh
  • {FORCE}: whether to force translation
  • {GLOSSARY}: glossary content (if any)
  • {STATUS_FILE_PATH}：.aigne/doc-smith/cache/task-status/{slug}.status

Batch execution workflow

Preparation phase

Before dispatching the first Task:

  1. rm -rf .aigne/doc-smith/cache/task-status && mkdir -p .aigne/doc-smith/cache/task-status(rebuild the directory, clear the old state)

Dispatch phase

Each Task is dispatched using run_in_background: true . All Tasks in a batch start at the same time.

Waiting phase

Check every 15 seconds the number of .status files:

find .aigne/doc-smith/cache/task-status -name '*.status' | wc -l
  • File count = number of tasks in the current batch → the batch is complete
  • Timeout: wait at most 10 minutes per batch; after timeout, report the missing documents
  • Do not read the background Task's output_file(may be 300K+), only read .status files

Collect results

find .aigne/doc-smith/cache/task-status -name '*.status' -exec cat {} +

1 line per file; all translation summaries combined usually do not exceed 20 lines.

Failure handling

  • .status content starts with "failed" → record the failure reason, do not block subsequent batches
  • Timeout without producing .status → mark as timed out, prompt the user in the final report to retry

Image backend pre-detection

Before translating images, the main agent performs one image backend detection. The detection logic is the same as the "backend detection" section of doc-smith-images :

  1. Check whether GEMINI_API_KEY is set → select gemini-sdk
  2. Otherwise check whether the AFS CLI is available → select afs-cli
  3. None available → Must use AskUserQuestion to let the user choose(configure API Key / install AFS CLI / skip image translation); automatically defaulting to skip is prohibited

Record the detection result as {IMAGE_BACKEND}, and all subsequent image translation calls use --backend {IMAGE_BACKEND}consistently. It can only be set to skip。

when the user explicitly chooses to skip.Translate images

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

Sync images to dist

Translated images are saved in the assets source directory and need to be synced to the dist release directory:

cp .aigne/doc-smith/assets/{key}/images/{target}.png \
   .aigne/doc-smith/dist/assets/{key}/images/{target}.png

Update image references

The image paths in the translated HTML need to have their language suffix updated:

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

AI inspection

After translation and nav.js rebuild are complete, read dist/ Generated HTML files (spot-check 1-2 pages per language) to verify the output meets expectations. If there are issues, directly modify the HTML files to fix them.

Translation Report

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

Error Handling

  • Workspace does not exist: prompt to first use /doc-smith to generate documents
  • Target language is the same as the source language: prompt to specify a different language
  • Invalid document path: list valid paths for the user's reference
  • Partial translation failure: report the failed documents and suggest using --path to retry individually