ComfyUI-Lora-Manager/docs/i18n.md

# 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;
}
```