mirror of
https://github.com/Comfy-Org/ComfyUI_frontend.git
synced 2026-01-26 19:09:52 +00:00
[docs] Improve language contribution process (#4409)
This commit is contained in:
Christian Byrne
172
src/locales/CONTRIBUTING.md
Normal file
172
src/locales/CONTRIBUTING.md
Normal 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.*
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user