ComfyUI_frontend/src/locales/CONTRIBUTING.md

Contributing Translations to ComfyUI

Quick Start for New Languages

1. Let us know - Open an issue or reach out on Discord to request a new language
2. Get technical setup help - We'll help configure the initial files or you can follow the technical process below
3. Automatic translation - Our CI system will generate translations using OpenAI when you create a PR
4. Review and refine - You can improve the auto-generated translations and become a maintainer for that language

Technical Process (Confirmed Working)

Prerequisites

• Node.js installed
• Git/GitHub knowledge
• OpenAI API key (optional - CI will handle translations)

Step 1: Update Configuration Files

Time required: ~10 minutes

1.1 Update .i18nrc.cjs

Add your language code to the outputLocales array:

module.exports = defineConfig({
  // ... existing config
  outputLocales: ['zh', 'zh-TW', 'ru', 'ja', 'ko', 'fr', 'es', 'tr'], // Add your language here
  reference: `Special names to keep untranslated: flux, photomaker, clip, vae, cfg, stable audio, stable cascade, stable zero, controlnet, lora, HiDream.
  'latent' is the short form of 'latent space'.
  'mask' is in the context of image processing.
  Note: For Traditional Chinese (Taiwan), use Taiwan-specific terminology and traditional characters.
  `
});

1.2 Update src/constants/coreSettings.ts

Add your language to the dropdown options:

{
  id: 'Comfy.Locale',
  name: 'Language',
  type: 'combo',
  options: [
    { value: 'en', text: 'English' },
    { value: 'zh', text: '中文' },
    { value: 'zh-TW', text: '繁體中文 (台灣)' }, // Add your language here
    { value: 'ru', text: 'Русский' },
    { value: 'ja', text: '日本語' },
    { value: 'ko', text: '한국어' },
    { value: 'fr', text: 'Français' },
    { value: 'es', text: 'Español' }
  ],
  defaultValue: () => navigator.language.split('-')[0] || 'en'
},

1.3 Update src/i18n.ts

Add imports for your new language files:

// Add these imports (replace zh-TW with your language code)
import zhTWCommands from './locales/zh-TW/commands.json'
import zhTW from './locales/zh-TW/main.json'
import zhTWNodes from './locales/zh-TW/nodeDefs.json'
import zhTWSettings from './locales/zh-TW/settings.json'

// Add to the messages object
const messages = {
  en: buildLocale(en, enNodes, enCommands, enSettings),
  zh: buildLocale(zh, zhNodes, zhCommands, zhSettings),
  'zh-TW': buildLocale(zhTW, zhTWNodes, zhTWCommands, zhTWSettings), // Add this line
  // ... other languages
}

Step 2: Generate Translation Files

Option A: Local Generation (Optional)

# Only if you have OpenAI API key configured
pnpm locale

Option B: Let CI Handle It (Recommended)

• Create your PR with the configuration changes above
• Important: Translation files will be generated during release PRs, not feature PRs
• Empty JSON files are fine - they'll be populated during the next release workflow
• For urgent translation needs, maintainers can manually trigger the workflow

Step 3: Test Your Changes

pnpm typecheck  # Check for TypeScript errors
pnpm dev        # Start development server

Testing checklist:

• Language appears in ComfyUI Settings > Locale dropdown
• Can select the new language without errors
• Partial translations display correctly
• UI falls back to English for untranslated strings
• No console errors when switching languages

Step 4: Submit PR

1. Create PR with your configuration changes
2. CI will run and automatically populate translation files
3. Request review from language maintainers: @Yorha4D @KarryCharon @DorotaLuna @shinshin86
4. Get added to CODEOWNERS as a reviewer for your language

What Happens in CI

Our automated translation workflow now runs on release PRs (version-bump-* branches) to improve development performance:

For Feature PRs (Regular Development)

• No automatic translations - faster reviews and fewer conflicts
• English-only development - new strings show in English until release
• Focus on functionality - reviewers see only your actual changes

For Release PRs (version-bump-* branches)

1. Collects strings: Scans the UI for translatable text
2. Updates English files: Ensures all strings are captured
3. Generates translations: Uses OpenAI API to translate to all configured languages
4. Commits back: Automatically updates the release PR with complete translations

Manual Translation Updates

If urgent translation updates are needed outside of releases, maintainers can:

• Trigger the "Update Locales" workflow manually from GitHub Actions
• The workflow supports manual dispatch for emergency translation updates

File Structure

Each language has 4 translation files:

• main.json - Main UI text (~2000+ entries)
• commands.json - Command descriptions (~200+ entries)
• settings.json - Settings panel (~400+ entries)
• nodeDefs.json - Node definitions (~varies based on installed nodes)

Translation Quality

• Auto-translations are high quality but may need refinement
• Technical terms are preserved (flux, photomaker, clip, vae, etc.)
• Context-aware translations based on UI usage
• Native speaker review is encouraged for quality improvements

Common Issues & Solutions

Issue: TypeScript errors on imports

Solution: Ensure your language code matches exactly in all three files

Issue: Empty translation files

Solution: This is normal - CI will populate them when you create a PR

Issue: Language not appearing in dropdown

Solution: Check that the language code in coreSettings.ts matches your other files exactly

Issue: Rate limits during local translation

Solution: This is expected - let CI handle the translation generation

Regional Variants

For regional variants (like zh-TW for Taiwan), use:

• Language-region codes: zh-TW, pt-BR, en-US
• Specific terminology: Add region-specific context to the reference string
• Native display names: Use the local language name in the dropdown

Getting Help

• Tag translation maintainers: @Yorha4D @KarryCharon @DorotaLuna @shinshin86
• Check existing language PRs for examples
• Open an issue describing your language addition request
• Reference this tested process - we've confirmed it works!

Becoming a Language Maintainer

After your language is added:

1. Get added to CODEOWNERS for your language files
2. Review future PRs affecting your language
3. Coordinate with other native speakers for quality improvements
4. Help maintain translations as the UI evolves

---

This process was tested and confirmed working with Traditional Chinese (Taiwan) addition.