managing-translations

name

managing-translations

description

Manages internationalization and translations for ComfyUI workflow templates. Syncs translations, adds new languages, checks translation coverage, and manages locale files. Use when asked to: translate, add translations, sync translations, check translations, missing translations, add a language, localize, internationalize, i18n, update translations, translation status, which templates need translation, language support, sync locales, translate description, translate title, add Chinese, add Japanese, add Spanish, multi-language, multilingual. Triggers on: translate, translation, i18n, locale, language, localize, internationalize, sync translations, missing translations.

Managing Translations

Overview

The repo supports 11 languages. The English master file is templates/index.json. Locale files follow the pattern templates/index.{locale}.json:

Code	Language	File
en	English	templates/index.json (master)
zh	Chinese (Simplified)	templates/index.zh.json
zh-TW	Chinese (Traditional)	templates/index.zh-TW.json
ja	Japanese	templates/index.ja.json
ko	Korean	templates/index.ko.json
es	Spanish	templates/index.es.json
fr	French	templates/index.fr.json
ru	Russian	templates/index.ru.json
tr	Turkish	templates/index.tr.json
ar	Arabic	templates/index.ar.json
pt-BR	Portuguese (Brazil)	templates/index.pt-BR.json

How Sync Works

Run the sync script to propagate changes from English master to all locale files:

python3 scripts/sync/sync_data.py --templates-dir templates

What sync does

• Technical fields (models, date, size, tags, etc.) are auto-copied from English master to all locales.
• Translatable fields (title, description) are preserved if already translated — they are NOT overwritten.
• New templates get English fallback text until translated.
• Tags are auto-translated using mappings defined in scripts/data/i18n.json.

Useful flags

• --dry-run — Preview changes without writing files.
• --force-sync-language-fields — Overwrite existing translations with English text (destructive — use with caution).

Translation Tracking

scripts/data/i18n.json stores:

• Translation status for each template (per language).
• Tag translation mappings (English → each language).
• Category title translations.

Adding Translations for a Template

1. Edit scripts/data/i18n.json to add translations under the template's name.

2. Run the sync script:

   python3 scripts/sync/sync_data.py --templates-dir templates
   

3. Verify the locale files were updated correctly.

Checking Translation Coverage

• Look at scripts/.output/missing_translations_report.json for untranslated entries.
• Or manually compare a locale file against index.json to find templates with English-only text.

Site-Level i18n (Separate System)

The template site (site/) has its own i18n system for UI strings — this is separate from the template translation system above:

• site/src/i18n/config.ts — Language definitions.
• site/src/i18n/ui.ts — UI string translations.
• site/src/i18n/utils.ts — URL localization helpers.
• Site sync: pnpm run sync (from site/ directory) reads all locale index files.

After Changes, Always Run

python3 scripts/sync/sync_data.py --templates-dir templates
python scripts/validate/validate_templates.py

Rules

• English index.json is the master — always edit it first for structural changes.
• Never manually edit locale files for technical fields — use the sync script.
• Translatable fields (title, description) CAN be manually edited in locale files.
• After adding a new template to index.json, always run sync to propagate to all locales.
• Tag translations go in scripts/data/i18n.json, not in the locale files directly.