diff --git a/src/locales/CONTRIBUTING.md b/src/locales/CONTRIBUTING.md new file mode 100644 index 000000000..76fe98fe1 --- /dev/null +++ b/src/locales/CONTRIBUTING.md @@ -0,0 +1,172 @@ +# 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: + +```javascript +module.exports = defineConfig({ + // ... existing config + outputLocales: ['zh', 'zh-TW', 'ru', 'ja', 'ko', 'fr', 'es'], // 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: + +```typescript +{ + 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: + +```typescript +// 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) +```bash +# Only if you have OpenAI API key configured +npm run locale +``` + +#### Option B: Let CI Handle It (Recommended) +- Create your PR with the configuration changes above +- Our GitHub CI will automatically generate translation files +- Empty JSON files are fine - they'll be populated by the workflow + +### Step 3: Test Your Changes + +```bash +npm run typecheck # Check for TypeScript errors +npm run 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: +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 your PR with complete translations + +## 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.* \ No newline at end of file diff --git a/src/locales/README.md b/src/locales/README.md index f0280ea49..50bec9eb9 100644 --- a/src/locales/README.md +++ b/src/locales/README.md @@ -14,68 +14,17 @@ Our project supports multiple languages using `vue-i18n`. This allows users arou ## How to Add a New Language -We welcome the addition of new languages. You can add a new language by following these steps: +Want to add a new language to ComfyUI? See our detailed [Contributing Guide](./CONTRIBUTING.md) with step-by-step instructions and confirmed working process. -### 1\. Generate language files +### Quick Start +1. Open an issue or reach out on Discord to request a new language +2. Follow the [technical process](./CONTRIBUTING.md#technical-process-confirmed-working) or ask for help +3. Our CI will automatically generate translations using OpenAI +4. Become a maintainer for your language -We use [lobe-i18n](https://github.com/lobehub/lobe-cli-toolbox/blob/master/packages/lobe-i18n/README.md) as our translation tool, which integrates with LLM for efficient localization. - -Update the configuration file to include the new language(s) you wish to add: - -```javascript -const { defineConfig } = require('@lobehub/i18n-cli'); - -module.exports = defineConfig({ - entry: 'src/locales/en.json', // Base language file - entryLocale: 'en', - output: 'src/locales', - outputLocales: ['zh', 'ru', 'ja', 'ko', 'fr', 'es'], // Add the new language(s) here -}); -``` - -Set your OpenAI API Key by running the following command: - -```sh -npx lobe-i18n --option -``` - -Once configured, generate the translation files with: - -```sh -npx lobe-i18n locale -``` - -This will create the language files for the specified languages in the configuration. - -### 2\. Update i18n Configuration - -Import the newly generated locale file(s) in the `src/i18n.ts` file to include them in the application's i18n setup. - -### 3\. Enable Selection of the New Language - -Add the newly added language to the following item in `src/constants/coreSettings.ts`: - -```typescript -{ - id: 'Comfy.Locale', - name: 'Locale', - type: 'combo', - // Add the new language(s) here - options: [ - { value: 'en', text: 'English' }, - { value: 'zh', text: '中文' }, - { 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' - }, -``` - -This will make the new language selectable in the application's settings. - -### 4\. Test the Translations - -Start the development server, switch to the new language, and verify the translations. You can switch languages by opening the ComfyUI Settings and selecting from the `ComfyUI > Locale` dropdown box. +### File Structure +Each language has 4 translation files in `src/locales/[language-code]/`: +- `main.json` - Main UI text +- `commands.json` - Command descriptions +- `settings.json` - Settings panel +- `nodeDefs.json` - Node definitions