i18n: terminology glossary + AI quality review (#1124)

[comfyui-wiki]

Summary

Improves the docs translation pipeline with terminology consistency and AI quality review, addressing the term drift described in #1124 (e.g. "custom node" rendered as both 맞춤형 노드 and 커스텀 노드 in Korean).

Two features land here:

1. Terminology glossary — keep the same English term rendered consistently across pages.
2. AI quality review (LLM-as-a-judge) — an independent, cheaper model scores existing translations and flags issues.

Plus cleanup of obsolete ZH→JA leak-fixing tooling.

---

1. Terminology glossary

Three complementary mechanisms feed the translator, each for a different category of term:

Mechanism	Effect	Example	Maintained
preserve_terms (existing)	keep the term in English	checkpoint, LoRA, scheduler	by hand
glossary/frontend/{lang}.json	use the frontend's translation	workflow → 워크플로	machine-synced
glossary/overrides/{lang}.json	correct / extend the frontend	custom node → 커스텀 노드	by hand, wins

• glossary/frontend/{lang}.json — a machine mirror of the ComfyUI frontend locales (the authoritative source of term translations). Rebuilt wholesale by npm run glossary:sync; never hand-edited.
• glossary/overrides/{lang}.json — hand-maintained, wins over the mirror. The place to record a term decision (Inconsistent terminology in translated docs (no term-mapping mechanism) #1124) or drop a noisy frontend term:

  { "terms": { "custom node": "커스텀 노드" }, "ignore": ["title", "additional", "work"] }

• At translation time, only terms that actually appear in a document are selected (whole-word, longest-first, capped) and injected as preferred (not mandatory) hints, so the model keeps natural phrasing when a literal substitution would read awkwardly.
• New languages extend automatically: once a language is in translation-config.json, npm run glossary:sync generates its frontend mirror (provided the frontend ships that locale). The override file is optional.

Design notes

• The frontend UI locale is low signal as a glossary — full of button/toast text and function words whose UI rendering is wrong in prose (of → 중, work → 업무용). A curated common-word blocklist (not a length filter — node/model and work/mode are the same length) drops these at sync time; the long tail goes in override ignore.
• ComfyUI proper nouns with no settled translation belong in preserve_terms (expanded with embedding, scheduler, sampler, latent, etc.), kept in English — the opposite of the glossary.

npm run glossary:sync                 # rebuild the frontend mirror, all languages
npm run glossary:sync -- --lang ko    # one language
npm run glossary:sync:dry-run         # report counts without writing

2. AI quality review (LLM-as-a-judge)

npm run translate:review scores existing translations with an independent (typically cheaper) model on four axes — accuracy, completeness, terminology (checked against the glossary), and fluency — and lists concrete issues.

• Advisory, not blocking. Detailed scores and issues go to .github/i18n-logs/review/ (gitignored). Never blocks a PR; independent of the translation model's own === MISMATCHES === self-notes.
• Review state is committed. The reviewed English-source hash is stored as reviewSourceHash in the translated file's frontmatter (snippets: an MDX comment), mirroring translationSourceHash. This makes review state shared across the team and visible per file. Only the hash goes in frontmatter — scores/issues stay in the report.
• Incremental. By default only reviews translations that are up to date with English and not yet reviewed at that hash. Re-translation naturally invalidates the review stamp, so a changed file gets re-reviewed.
• Configurable judge via REVIEW_API_KEY / REVIEW_API_BASE_URL / REVIEW_API_MODEL (falls back to TRANSLATE_*). Retries with backoff on transient network / 5xx / 429 errors.

npm run translate:review                     # pending reviews, all languages
npm run translate:review -- --lang ko        # one language
npm run translate:review -- --all            # re-review everything
npm run translate:review -- --sample 20      # N pending files per language
npm run translate:review -- --min-score 4    # report files scoring below 4/5

Example of a real flagged finding from a trial run:

[ko] account/login.mdx — overall 4/5 (accuracy 3): "Sign in" mistranslated as 가입 (sign up) instead of 로그인; "Forgot password?" not using preferred terminology.

3. Cleanup

• Removed obsolete ZH→JA leak-fixing tooling (fix-zh-leaks.ts, zh-ja-dict.ts, check-ja.ts): the pipeline is English-primary now, so Chinese can't leak into Japanese, and these had no main-pipeline or CI references.

Docs & config

• New .github/scripts/i18n/README.md documenting the full i18n flow, glossary design, and quality review; root README and localized contributing guides updated.
• .env.local.example: added OpenRouter example, FRONTEND_LOCALES_PATH, and REVIEW_API_*.

Closes #1124

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
comfy	🟢 Ready	View Preview	Jun 10, 2026, 9:34 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[OneVth]

Thanks for picking this up so quickly! The override layer for recording term decisions is a cleaner approach than I had in mind. Looks great.