Comfy-Org/ComfyUI_frontend
1
0
Fork 0
mirror of https://github.com/Comfy-Org/ComfyUI_frontend.git synced 2026-04-28 02:02:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Improve language contribution process (#4409)

Browse Source
This commit is contained in:
Christian Byrne
2025-07-09 22:51:12 -07:00
committed by GitHub
parent 733c9f81b0
commit bc4753e119
2 changed files with 184 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
src/locales/CONTRIBUTING.md Normal file
View File

@@ -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.*

75
src/locales/README.md
View File

@@ -14,68 +14,17 @@ Our project supports multiple languages using `vue-i18n`. This allows users arou
## How to Add a New Language ## 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. ### File Structure
Each language has 4 translation files in `src/locales/[language-code]/`:
Update the configuration file to include the new language(s) you wish to add: - `main.json` - Main UI text
- `commands.json` - Command descriptions
```javascript - `settings.json` - Settings panel
const { defineConfig } = require('@lobehub/i18n-cli'); - `nodeDefs.json` - Node definitions
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.