mirror of
https://github.com/willmiao/ComfyUI-Lora-Manager.git
synced 2026-03-24 22:52:12 -03:00
Implement internationalization (i18n) system for LoRA Manager
- Added i18n support with automatic language detection based on browser settings. - Implemented translations for English (en) and Simplified Chinese (zh-CN). - Created utility functions for text replacement in HTML templates and JavaScript. - Developed a comprehensive translation key structure for various application components. - Added formatting functions for numbers, dates, and file sizes according to locale. - Included RTL language support and dynamic updates for DOM elements. - Created tests to verify the functionality of the i18n system.
This commit is contained in:
216
docs/i18n.md
Normal file
216
docs/i18n.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# LoRA Manager Internationalization (i18n)
|
||||
|
||||
This document explains how to use the internationalization system in LoRA Manager.
|
||||
|
||||
## Features
|
||||
|
||||
- Automatic language detection based on browser language
|
||||
- Support for English (en) and Simplified Chinese (zh-CN)
|
||||
- Fallback to English if the browser language is not supported
|
||||
- Dynamic text replacement in HTML templates
|
||||
- Number, date, and file size formatting according to locale
|
||||
- Right-to-Left (RTL) language support (framework ready)
|
||||
|
||||
## Browser Language Detection
|
||||
|
||||
The system automatically detects the user's browser language using:
|
||||
1. `navigator.language` - Primary browser language
|
||||
2. `navigator.languages[0]` - First language in the user's preferred languages
|
||||
3. Fallback to 'en' if no supported language is found
|
||||
|
||||
### Supported Language Codes
|
||||
|
||||
- `en` - English (default)
|
||||
- `zh-CN` - Simplified Chinese
|
||||
- `zh` - Falls back to Simplified Chinese
|
||||
|
||||
## Usage in HTML Templates
|
||||
|
||||
### Basic Text Translation
|
||||
|
||||
Add the `data-i18n` attribute to any HTML element:
|
||||
|
||||
```html
|
||||
<span data-i18n="header.appTitle">LoRA Manager</span>
|
||||
<button data-i18n="common.actions.save">Save</button>
|
||||
```
|
||||
|
||||
### Placeholder and Attribute Translation
|
||||
|
||||
For form inputs and other attributes:
|
||||
|
||||
```html
|
||||
<input type="text" data-i18n="header.search.placeholder" data-i18n-target="placeholder" placeholder="Search..." />
|
||||
<button data-i18n="loras.controls.refresh.title" data-i18n-target="title" title="Refresh model list">
|
||||
```
|
||||
|
||||
### Translation with Parameters
|
||||
|
||||
For dynamic content with variables:
|
||||
|
||||
```html
|
||||
<span data-i18n="loras.bulkOperations.selected" data-i18n-params='{"count": 5}'>5 selected</span>
|
||||
```
|
||||
|
||||
## Usage in JavaScript
|
||||
|
||||
### Import the i18n Helper
|
||||
|
||||
```javascript
|
||||
import { t, formatFileSize, formatDate, formatNumber } from './utils/i18nHelpers.js';
|
||||
```
|
||||
|
||||
### Basic Translation
|
||||
|
||||
```javascript
|
||||
// Simple translation
|
||||
const message = t('common.status.loading');
|
||||
|
||||
// Translation with parameters
|
||||
const selectedText = t('loras.bulkOperations.selected', { count: 5 });
|
||||
```
|
||||
|
||||
### Dynamic DOM Updates
|
||||
|
||||
```javascript
|
||||
import { setTranslatedText, setTranslatedAttribute, updateBulkSelectionCount } from './utils/i18nHelpers.js';
|
||||
|
||||
// Update text content
|
||||
setTranslatedText('#myButton', 'common.actions.save');
|
||||
|
||||
// Update attributes
|
||||
setTranslatedAttribute('#myInput', 'placeholder', 'header.search.placeholder');
|
||||
|
||||
// Update bulk selection count
|
||||
updateBulkSelectionCount(selectedItems.length);
|
||||
```
|
||||
|
||||
### Formatting Functions
|
||||
|
||||
```javascript
|
||||
// Format file size
|
||||
const sizeText = formatFileSize(1048576); // "1 MB" or "1 兆字节"
|
||||
|
||||
// Format date
|
||||
const dateText = formatDate(new Date(), { year: 'numeric', month: 'long', day: 'numeric' });
|
||||
|
||||
// Format number
|
||||
const numberText = formatNumber(1234.56, { minimumFractionDigits: 2 });
|
||||
```
|
||||
|
||||
## Page Initialization
|
||||
|
||||
Each page should call `initializePageI18n()` after the DOM is loaded:
|
||||
|
||||
```javascript
|
||||
import { initializePageI18n } from './utils/i18nHelpers.js';
|
||||
|
||||
document.addEventListener('DOMContentLoaded', async () => {
|
||||
// Initialize core application
|
||||
await appCore.initialize();
|
||||
|
||||
// Initialize page-specific functionality
|
||||
const myPage = new MyPageManager();
|
||||
await myPage.initialize();
|
||||
|
||||
// Initialize i18n for the page
|
||||
initializePageI18n();
|
||||
});
|
||||
```
|
||||
|
||||
## Translation Key Structure
|
||||
|
||||
Translation keys use dot notation for nested objects:
|
||||
|
||||
```
|
||||
common.actions.save → "Save" / "保存"
|
||||
header.navigation.loras → "LoRAs" / "LoRA 模型"
|
||||
loras.controls.sort.nameAsc → "A - Z" / "A - Z"
|
||||
```
|
||||
|
||||
### Key Categories
|
||||
|
||||
- `common.*` - Shared terms and actions
|
||||
- `header.*` - Header and navigation
|
||||
- `loras.*` - LoRA page specific
|
||||
- `recipes.*` - Recipe page specific
|
||||
- `checkpoints.*` - Checkpoint page specific
|
||||
- `embeddings.*` - Embedding page specific
|
||||
- `statistics.*` - Statistics page specific
|
||||
- `modals.*` - Modal dialogs
|
||||
- `errors.*` - Error messages
|
||||
- `success.*` - Success messages
|
||||
- `keyboard.*` - Keyboard shortcuts
|
||||
- `tooltips.*` - Tooltip text
|
||||
|
||||
## Adding New Languages
|
||||
|
||||
1. Create a new language file in `static/js/i18n/locales/`:
|
||||
|
||||
```javascript
|
||||
// Example: fr.js for French
|
||||
export const fr = {
|
||||
common: {
|
||||
actions: {
|
||||
save: 'Sauvegarder',
|
||||
cancel: 'Annuler',
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
},
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
2. Import and register the language in `static/js/i18n/index.js`:
|
||||
|
||||
```javascript
|
||||
import { fr } from './locales/fr.js';
|
||||
|
||||
class I18nManager {
|
||||
constructor() {
|
||||
this.locales = {
|
||||
'en': en,
|
||||
'zh-CN': zhCN,
|
||||
'zh': zhCN,
|
||||
'fr': fr, // Add new language
|
||||
};
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep keys descriptive**: Use clear, hierarchical key names
|
||||
2. **Consistent naming**: Follow the established pattern for similar elements
|
||||
3. **Fallback text**: Always provide fallback text in HTML for graceful degradation
|
||||
4. **Context-aware**: Group related translations logically
|
||||
5. **Parameter usage**: Use parameters for dynamic content instead of string concatenation
|
||||
6. **Testing**: Test with different languages to ensure UI layout works properly
|
||||
|
||||
## RTL Language Support
|
||||
|
||||
The system includes framework support for RTL languages:
|
||||
|
||||
```javascript
|
||||
// Check if current language is RTL
|
||||
if (i18n.isRTL()) {
|
||||
document.documentElement.setAttribute('dir', 'rtl');
|
||||
document.body.classList.add('rtl');
|
||||
}
|
||||
```
|
||||
|
||||
Add CSS for RTL support:
|
||||
|
||||
```css
|
||||
.rtl {
|
||||
direction: rtl;
|
||||
}
|
||||
|
||||
.rtl .some-element {
|
||||
text-align: right;
|
||||
margin-right: 0;
|
||||
margin-left: auto;
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user