Doc-Smith Document Translation

Usage

/doc-smith-localize --lang en                    # Translate all documents to English
/doc-smith-localize -l en -l ja                  # Translate to multiple languages
/doc-smith-localize -l en -p /overview           # Translate only the specified document
/doc-smith-localize -l en --force                # Force re-translation
/doc-smith-localize -l en --skip-images          # Skip image translation

Options

--lang <code>

-l

--path <docPath>

-p

--force

-f

--skip-images

Constraints

1. Workspace Constraints

• .aigne/doc-smith/config.yaml

  and

  planning/document-structure.yaml

  must exist
• If they do not exist, prompt the user to generate documents using

  /doc-smith

  first

2. Parameter Validation Constraints

• Target language cannot be the same as the source language (locale in config.yaml)
• The path specified by

  --path

  must exist in document-structure.yaml
• Throw an error if no valid languages are left after filtering

3. Incremental Translation Constraints

• Determine whether translation is needed based on the SHA256 hash (sourceHash) of the source HTML
• Automatically skip documents where the hash has not changed (unless

  --force

  is used)
• Do not overwrite existing translations or modify .meta.yaml if translation fails

4. Task Distribution Constraints

• Each document to each language is an independent translation task
• Distribute via Task(references/translate-document.md), execute in parallel
• Max 5 parallel Tasks per batch, split into batches if exceeded
• If a glossary exists (

  .aigne/doc-smith/glossary.yaml

  or

  .md

  ), pass it to each Task

5. Image Translation Constraints

• If

  --skip-images

  is not specified, scan image resources in assets
• Skip conditions (meet any):

  generation.shared: true

  , target language already exists, source language image does not exist
• Use

  /doc-smith-images --update

  to translate text in images
• Update the languages and translations fields in the image's .meta.yaml after translation

6. Config Update Constraints

• After translation is completed, add the target language to the

  translateLanguages

  array in config.yaml
• Avoid adding existing languages repeatedly
• Verify that config.yaml is correct after update

7. nav.js Rebuild Constraints

• Must rebuild nav.js after Config update:
  bash

  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 critical for the language switch function to take effect and must not be skipped

HTML-to-HTML Translation Model

Source HTML → Extract translatable regions → Translate → Assemble target HTML → Save
dist/{source}/docs/{path}.html → dist/{target}/docs/{path}.html

• Text inside

  <title>

  tag
• content attribute of

  <meta name="description">

• HTML inside

  <main data-ds="content">

  tag
• HTML inside

  <nav data-ds="toc">

  tag

Translation Quality Requirements

• Terminology consistency: Use glossaries to maintain unified professional terms
• HTML structure preservation: Keep tags intact, only translate text content
• Context understanding: Choose appropriate translations based on the technical document context
• Natural fluency: Translation results conform to the target language's usage habits

Key Processes

Parallel Document Translation

Use separate Task tools to translate the following documents in parallel according to the references/translate-document.md process:
- docPath=/overview, targetLanguage=en, sourceLanguage=zh, force=false
- docPath=/api/auth, targetLanguage=en, sourceLanguage=zh, force=false

Image Translation

/doc-smith-images "Translate text in images from {source} to {target}, keeping layout and style unchanged" \
  --update .aigne/doc-smith/assets/{key}/images/{source}.png \
  --savePath .aigne/doc-smith/assets/{key}/images/{target}.png \
  --locale {target}

Update Image References

• Match

  images/{source}.png

  → replace with

  images/{target}.png

  (only if the target language image exists)

AI Inspection

dist/

Translation Report

Error Handling

• Workspace does not exist: Prompt the user to generate documents using

  /doc-smith

  first
• Target language is the same as source language: Prompt to specify a different language
• Invalid document path: List valid paths for user reference
• Partial translation failure: Report failed documents, suggest retrying individually with

  --path