Skip to content

Commit bc4753e

Browse files
christian-byrnechristian-byrne
authored
[docs] Improve language contribution process (#4409)
1 parent 733c9f8 commit bc4753e

File tree

2 files changed

+186
-65
lines changed

2 files changed

+186
-65
lines changed

‎src/locales/CONTRIBUTING.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Contributing Translations to ComfyUI
2+
3+
## Quick Start for New Languages
4+
5+
1. **Let us know** - Open an issue or reach out on Discord to request a new language
6+
2. **Get technical setup help** - We'll help configure the initial files or you can follow the technical process below
7+
3. **Automatic translation** - Our CI system will generate translations using OpenAI when you create a PR
8+
4. **Review and refine** - You can improve the auto-generated translations and become a maintainer for that language
9+
10+
## Technical Process (Confirmed Working)
11+
12+
### Prerequisites
13+
- Node.js installed
14+
- Git/GitHub knowledge
15+
- OpenAI API key (optional - CI will handle translations)
16+
17+
### Step 1: Update Configuration Files
18+
19+
**Time required: ~10 minutes**
20+
21+
#### 1.1 Update `.i18nrc.cjs`
22+
Add your language code to the `outputLocales` array:
23+
24+
```javascript
25+
module.exports = defineConfig({
26+
// ... existing config
27+
outputLocales: ['zh', 'zh-TW', 'ru', 'ja', 'ko', 'fr', 'es'], // Add your language here
28+
reference: `Special names to keep untranslated: flux, photomaker, clip, vae, cfg, stable audio, stable cascade, stable zero, controlnet, lora, HiDream.
29+
'latent' is the short form of 'latent space'.
30+
'mask' is in the context of image processing.
31+
Note: For Traditional Chinese (Taiwan), use Taiwan-specific terminology and traditional characters.
32+
`
33+
});
34+
```
35+
36+
#### 1.2 Update `src/constants/coreSettings.ts`
37+
Add your language to the dropdown options:
38+
39+
```typescript
40+
{
41+
id: 'Comfy.Locale',
42+
name: 'Language',
43+
type: 'combo',
44+
options: [
45+
{ value: 'en', text: 'English' },
46+
{ value: 'zh', text: '中文' },
47+
{ value: 'zh-TW', text: '繁體中文 (台灣)' }, // Add your language here
48+
{ value: 'ru', text: 'Русский' },
49+
{ value: 'ja', text: '日本語' },
50+
{ value: 'ko', text: '한국어' },
51+
{ value: 'fr', text: 'Français' },
52+
{ value: 'es', text: 'Español' }
53+
],
54+
defaultValue: () => navigator.language.split('-')[0] || 'en'
55+
},
56+
```
57+
58+
#### 1.3 Update `src/i18n.ts`
59+
Add imports for your new language files:
60+
61+
```typescript
62+
// Add these imports (replace zh-TW with your language code)
63+
import zhTWCommands from './locales/zh-TW/commands.json'
64+
import zhTW from './locales/zh-TW/main.json'
65+
import zhTWNodes from './locales/zh-TW/nodeDefs.json'
66+
import zhTWSettings from './locales/zh-TW/settings.json'
67+
68+
// Add to the messages object
69+
const messages = {
70+
en: buildLocale(en, enNodes, enCommands, enSettings),
71+
zh: buildLocale(zh, zhNodes, zhCommands, zhSettings),
72+
'zh-TW': buildLocale(zhTW, zhTWNodes, zhTWCommands, zhTWSettings), // Add this line
73+
// ... other languages
74+
}
75+
```
76+
77+
### Step 2: Generate Translation Files
78+
79+
#### Option A: Local Generation (Optional)
80+
```bash
81+
# Only if you have OpenAI API key configured
82+
npm run locale
83+
```
84+
85+
#### Option B: Let CI Handle It (Recommended)
86+
- Create your PR with the configuration changes above
87+
- Our GitHub CI will automatically generate translation files
88+
- Empty JSON files are fine - they'll be populated by the workflow
89+
90+
### Step 3: Test Your Changes
91+
92+
```bash
93+
npm run typecheck # Check for TypeScript errors
94+
npm run dev # Start development server
95+
```
96+
97+
**Testing checklist:**
98+
- [ ] Language appears in ComfyUI Settings > Locale dropdown
99+
- [ ] Can select the new language without errors
100+
- [ ] Partial translations display correctly
101+
- [ ] UI falls back to English for untranslated strings
102+
- [ ] No console errors when switching languages
103+
104+
### Step 4: Submit PR
105+
106+
1. **Create PR** with your configuration changes
107+
2. **CI will run** and automatically populate translation files
108+
3. **Request review** from language maintainers: @Yorha4D @KarryCharon @DorotaLuna @shinshin86
109+
4. **Get added to CODEOWNERS** as a reviewer for your language
110+
111+
## What Happens in CI
112+
113+
Our automated translation workflow:
114+
1. **Collects strings**: Scans the UI for translatable text
115+
2. **Updates English files**: Ensures all strings are captured
116+
3. **Generates translations**: Uses OpenAI API to translate to all configured languages
117+
4. **Commits back**: Automatically updates your PR with complete translations
118+
119+
## File Structure
120+
121+
Each language has 4 translation files:
122+
- `main.json` - Main UI text (~2000+ entries)
123+
- `commands.json` - Command descriptions (~200+ entries)
124+
- `settings.json` - Settings panel (~400+ entries)
125+
- `nodeDefs.json` - Node definitions (~varies based on installed nodes)
126+
127+
## Translation Quality
128+
129+
- **Auto-translations are high quality** but may need refinement
130+
- **Technical terms** are preserved (flux, photomaker, clip, vae, etc.)
131+
- **Context-aware** translations based on UI usage
132+
- **Native speaker review** is encouraged for quality improvements
133+
134+
## Common Issues & Solutions
135+
136+
### Issue: TypeScript errors on imports
137+
**Solution**: Ensure your language code matches exactly in all three files
138+
139+
### Issue: Empty translation files
140+
**Solution**: This is normal - CI will populate them when you create a PR
141+
142+
### Issue: Language not appearing in dropdown
143+
**Solution**: Check that the language code in `coreSettings.ts` matches your other files exactly
144+
145+
### Issue: Rate limits during local translation
146+
**Solution**: This is expected - let CI handle the translation generation
147+
148+
## Regional Variants
149+
150+
For regional variants (like zh-TW for Taiwan), use:
151+
- **Language-region codes**: `zh-TW`, `pt-BR`, `en-US`
152+
- **Specific terminology**: Add region-specific context to the reference string
153+
- **Native display names**: Use the local language name in the dropdown
154+
155+
## Getting Help
156+
157+
- **Tag translation maintainers**: @Yorha4D @KarryCharon @DorotaLuna @shinshin86
158+
- **Check existing language PRs** for examples
159+
- **Open an issue** describing your language addition request
160+
- **Reference this tested process** - we've confirmed it works!
161+
162+
## Becoming a Language Maintainer
163+
164+
After your language is added:
165+
1. **Get added to CODEOWNERS** for your language files
166+
2. **Review future PRs** affecting your language
167+
3. **Coordinate with other native speakers** for quality improvements
168+
4. **Help maintain translations** as the UI evolves
169+
170+
---
171+
172+
*This process was tested and confirmed working with Traditional Chinese (Taiwan) addition.*

‎src/locales/README.md‎

Lines changed: 14 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -14,68 +14,17 @@ Our project supports multiple languages using `vue-i18n`. This allows users arou
1414

1515
## How to Add a New Language
1616

17-
We welcome the addition of new languages. You can add a new language by following these steps:
18-
19-
### 1\. Generate language files
20-
21-
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.
22-
23-
Update the configuration file to include the new language(s) you wish to add:
24-
25-
```javascript
26-
const { defineConfig } = require('@lobehub/i18n-cli');
27-
28-
module.exports = defineConfig({
29-
entry: 'src/locales/en.json', // Base language file
30-
entryLocale: 'en',
31-
output: 'src/locales',
32-
outputLocales: ['zh', 'ru', 'ja', 'ko', 'fr', 'es'], // Add the new language(s) here
33-
});
34-
```
35-
36-
Set your OpenAI API Key by running the following command:
37-
38-
```sh
39-
npx lobe-i18n --option
40-
```
41-
42-
Once configured, generate the translation files with:
43-
44-
```sh
45-
npx lobe-i18n locale
46-
```
47-
48-
This will create the language files for the specified languages in the configuration.
49-
50-
### 2\. Update i18n Configuration
51-
52-
Import the newly generated locale file(s) in the `src/i18n.ts` file to include them in the application's i18n setup.
53-
54-
### 3\. Enable Selection of the New Language
55-
56-
Add the newly added language to the following item in `src/constants/coreSettings.ts`:
57-
58-
```typescript
59-
{
60-
id: 'Comfy.Locale',
61-
name: 'Locale',
62-
type: 'combo',
63-
// Add the new language(s) here
64-
options: [
65-
{ value: 'en', text: 'English' },
66-
{ value: 'zh', text: '中文' },
67-
{ value: 'ru', text: 'Русский' },
68-
{ value: 'ja', text: '日本語' },
69-
{ value: 'ko', text: '한국어' },
70-
{ value: 'fr', text: 'Français' },
71-
{ value: 'es', text: 'Español' }
72-
],
73-
defaultValue: navigator.language.split('-')[0] || 'en'
74-
},
75-
```
76-
77-
This will make the new language selectable in the application's settings.
78-
79-
### 4\. Test the Translations
80-
81-
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.
17+
Want to add a new language to ComfyUI? See our detailed [Contributing Guide](./CONTRIBUTING.md) with step-by-step instructions and confirmed working process.
18+
19+
### Quick Start
20+
1. Open an issue or reach out on Discord to request a new language
21+
2. Follow the [technical process](./CONTRIBUTING.md#technical-process-confirmed-working) or ask for help
22+
3. Our CI will automatically generate translations using OpenAI
23+
4. Become a maintainer for your language
24+
25+
### File Structure
26+
Each language has 4 translation files in `src/locales/[language-code]/`:
27+
- `main.json` - Main UI text
28+
- `commands.json` - Command descriptions
29+
- `settings.json` - Settings panel
30+
- `nodeDefs.json` - Node definitions

0 commit comments

Comments
 (0)