Docs I18n Translate

Docs i18n Translation

Translate Mintlify docs (not CMS). English is source of truth; ja / zh / ko are generated under {lang}/ and snippets/{lang}/.

Separate from CMS: pnpm cms:prepare writes gitignored .github/scripts/cms/staging/ for Strapi. See skill cms-changelog-sync.

Architecture

index.mdx, changelog/index.mdx, …   ← English (edit here)
        │
        ▼  pnpm translate            ← MDX only (does NOT touch docs.json)
{ja,zh,ko}/…                        ← translated MDX (commit to git)
snippets/{ja,zh,ko}/…
        │
        ▼  only if EN nav changed
pnpm translate:sync-docs-json       ← mirror nav paths in docs.json (opt-in)

Incremental: each file stores translationSourceHash in frontmatter. Unchanged English → skip.

Environment (.env.local)

Requires Bun.

Commands

Logs (gitignored): .github/i18n-logs/translate/

Standard workflow

After editing English MDX

pnpm translate:dry-run                    # see pending
pnpm translate -- changelog/index.mdx   # or specific paths
pnpm translate:check-truncation         # if long page / changelog

Small English edits (manual translation)

When only a line or paragraph changed:

# 1. Edit English + update zh/ja/ko by hand (or ask Cursor to patch matching sections)
# 2. Sync hashes so translate skips the file
pnpm translate:sync-hash -- path/to/page.mdx
pnpm translate:sync-hash -- --verify path/to/page.mdx   # optional sanity check

For larger or new sections, use pnpm translate -- path/to/page.mdx (chunked pages only re-translate changed ## sections when auto_chunk applies).

Changelog (changelog/index.mdx)

• Strategy: update_blocks (configured in translation-config.json)
• Only new or changed <Update label="vX"> blocks are translated (by label + translationBlockHashes)
• Dates in description are localized automatically (ja/zh/ko formats)
• Block hashes stored in translationBlockHashes frontmatter

Omit from English changelog when triaging ComfyUI commits — these are ComfyUI-WIKI sync PRs, not core product features:

Do not add bullets for dependency-only version bumps. See also cms-changelog-sync for CMS popup rules.

pnpm translate -- changelog/index.mdx
pnpm translate -- changelog/index.mdx --lang zh

Long pages (truncation risk)

Oversized individual ## blocks (e.g. many Mintlify Tabs) are sub-chunked when they exceed auto_chunk.max_block_chars (default 6000): Tabs → ### → fence-safe size splits. Invalid/truncated blocks stay pending (hash not updated).

Checkpoints per block — safe to resume after interrupt.

pnpm translate -- tutorials/partner-nodes/pricing.mdx --lang ko
pnpm translate:check-truncation -- --lang ko
pnpm translate:repair-truncated -- --lang ko

Terminology (glossary)

Three layers — see .github/scripts/i18n/README.md for detail:

pnpm glossary:sync              # after frontend locale updates
# Edit overrides/{lang}.json for term decisions
# Edit preserve_terms for English-only terms

Never hand-edit glossary/frontend/ — run glossary:sync.

Skipped paths

translation-config.json → skip_paths: e.g. built-in-nodes (not auto-translated).

Agent checklist

When user updates English docs and needs translations:

• Identify changed files (or run pnpm translate:dry-run)
• For small edits: hand-update translations, then pnpm translate:sync-hash -- <path>
• For larger edits: run pnpm translate for affected paths — not cms:prepare unless CMS/Strapi
• For changelog, translate docs zh/changelog/ etc., not CMS staging
• After long pages, run pnpm translate:check-truncation
• Commit translated MDX + updated translationSourceHash / translationBlockHashes
• Do not commit .github/i18n-logs/
• Do not expect pnpm translate to edit docs.json; if EN nav structure changed, run pnpm translate:sync-docs-json (or --with-docs-json) separately
• Optional quality pass: skill docs-i18n-review

Key files

Troubleshooting

Docs vs CMS translation