# Internationalization (I18N)

This guide explains the multi-language support system in CrossPoint Reader.

## Overview

CrossPoint Reader supports multiple languages for the user interface:

- **English** (Default)
- **Chinese Simplified** (简体中文)
- **Japanese** (日本語)

All UI text, menus, settings, and system messages are translated.

---

## Changing Language

1. Go to **Settings** → **System**
2. Select **Language**
3. Choose your preferred language from the list:
   - **English** - Displayed as "English"
   - **简体中文** - Displayed as "简体中文" (Chinese Simplified)
   - **日本語** - Displayed as "日本語" (Japanese)
4. The interface will update immediately

**Note:** Language changes take effect immediately without requiring a restart.

---

## Supported Languages

### English (Default)

The default language. All text is displayed in English.

### Chinese Simplified (简体中文)

Full Chinese translation including:
- All menu items and settings
- System messages and prompts
- Button labels and hints
- Error messages

**Requirements:** CJK UI font must be enabled for proper character display.

### Japanese (日本語)

Full Japanese translation including:
- All menu items and settings
- System messages and prompts
- Button labels and hints
- Error messages

**Requirements:** CJK UI font must be enabled for proper character display.

---

## Language and Font Relationship

When using Chinese or Japanese:

1. **Enable CJK UI Font** - Go to Settings → Display → UI Font
2. **Select a font** that supports your language's characters
3. **Change language** - The UI will now display correctly

If CJK font is not enabled, Chinese/Japanese characters may display as boxes or question marks.

---

## For Developers

### Adding New Translations

#### 1. Add String ID

In `lib/I18n/I18n.h`, add a new entry to the `StrId` enum:

```cpp
enum class StrId : uint16_t {
    // ... existing entries ...
    MY_NEW_STRING,
    // ... more entries ...
    _COUNT  // Must be last
};
```

#### 2. Add Translations

In `lib/I18n/I18n.cpp`, add translations to each language array:

```cpp
// English
static const char* const STRINGS_EN[] = {
    // ... existing strings ...
    "My New String",
    // ... more strings ...
};

// Chinese Simplified
static const char* const STRINGS_ZH[] = {
    // ... existing strings ...
    "\xE6\x88\x91\xE7\x9A\x84\xE6\x96\xB0\xE5\xAD\x97\xE7\xAC\xA6\xE4\xB8\xB2",  // 我的新字符串
    // ... more strings ...
};

// Japanese
static const char* const STRINGS_JA[] = {
    // ... existing strings ...
    "\xE6\x96\xB0\xE3\x81\x97\xE3\x81\x84\xE6\x96\x87\xE5\xAD\x97\xE5\x88\x97",  // 新しい文字列
    // ... more strings ...
};
```

**Important:**
- Arrays must have the same number of entries
- Use UTF-8 hex encoding for non-ASCII characters
- Keep entries in the same order as the enum

#### 3. Use in Code

```cpp
#include <I18n.h>

// Using the TR() macro (recommended)
renderer.drawText(font, x, y, TR(MY_NEW_STRING));

// Using I18N.get() directly
const char* text = I18N.get(StrId::MY_NEW_STRING);
```

### UTF-8 Hex Encoding

For non-ASCII characters, use UTF-8 hex encoding:

| Character | UTF-8 Hex |
|-----------|-----------|
| 中 | `\xE4\xB8\xAD` |
| 文 | `\xE6\x96\x87` |
| 日 | `\xE6\x97\xA5` |
| 本 | `\xE6\x9C\xAC` |

**Python helper:**
```python
def to_utf8_hex(text):
    return ''.join(f'\\x{b:02X}' for b in text.encode('utf-8'))

print(to_utf8_hex("设置"))  # \xE8\xAE\xBE\xE7\xBD\xAE
```

### I18N API Reference

```cpp
// Get the singleton instance
I18n& i18n = I18n::getInstance();

// Or use the global macro
I18N.get(StrId::SETTINGS);

// Get translated string
const char* text = I18N.get(StrId::SETTINGS);

// Set language
I18N.setLanguage(Language::ZH);

// Get current language
Language lang = I18N.getLanguage();

// Save language setting to file
I18N.saveSettings();

// Load language setting from file
I18N.loadSettings();
```

### Language Enum

```cpp
enum class Language : uint8_t {
    EN = 0,  // English
    ZH = 1,  // Chinese Simplified
    JA = 2,  // Japanese
    _COUNT   // Number of languages
};
```

---

## String Categories

The I18N system organizes strings into categories:

### Navigation & Actions
- `BACK`, `CONFIRM`, `CANCEL`, `SELECT`, `EXIT`, `DONE`

### Settings Categories
- `CAT_DISPLAY`, `CAT_READER`, `CAT_CONTROLS`, `CAT_SYSTEM`

### Display Settings
- `SLEEP_SCREEN`, `STATUS_BAR`, `REFRESH_FREQ`, etc.

### Reader Settings
- `FONT_SIZE`, `LINE_SPACING`, `ORIENTATION`, etc.

### System Settings
- `LANGUAGE`, `KOREADER_SYNC`, `CALIBRE_SETTINGS`, etc.

### Status Messages
- `CONNECTING`, `CONNECTED`, `FAILED`, `SUCCESS`, etc.

### File Transfer
- `FILE_TRANSFER`, `HOTSPOT_MODE`, `NETWORK_PREFIX`, etc.

---

## File Storage

Language settings are stored in:
```
/.crosspoint/i18n.bin
```

This file contains:
- Current language selection (1 byte)

---

## Adding a New Language

To add support for a new language:

1. **Add language to enum** in `lib/I18n/I18n.h`:
   ```cpp
   enum class Language : uint8_t {
       EN = 0,
       ZH = 1,
       JA = 2,
       KO = 3,  // New: Korean
       _COUNT
   };
   ```

2. **Create translation array** in `lib/I18n/I18n.cpp`:
   ```cpp
   static const char* const STRINGS_KO[] = {
       // All strings translated to Korean
   };
   ```

3. **Add to language arrays**:
   ```cpp
   static const char* const* const LANGUAGE_STRINGS[] = {
       STRINGS_EN,
       STRINGS_ZH,
       STRINGS_JA,
       STRINGS_KO,  // New
   };
   ```

4. **Add language name** for the language selection UI:
   ```cpp
   // In LanguageSelectActivity or I18n
   const char* languageNames[] = {
       "English",
       "简体中文",
       "日本語",
       "한국어",  // New
   };
   ```

5. **Ensure CJK font support** for the new language's characters

---

## Best Practices

1. **Keep translations concise** - E-ink displays have limited space
2. **Test on device** - Some characters may render differently
3. **Use consistent terminology** - Keep translations consistent across the UI
4. **Consider context** - Same word may need different translations in different contexts
5. **Update all languages** - When adding new strings, add translations for all languages

---

## Troubleshooting

### Characters showing as boxes

1. Enable CJK UI font in Settings → Display
2. Ensure the font includes the required characters
3. Check that the font file is not corrupted

### Language not saving

1. Check SD card is not write-protected
2. Verify `/.crosspoint/` directory exists
3. Check available space on SD card

### Missing translations

1. Verify string ID exists in the enum
2. Check all language arrays have the same number of entries
3. Rebuild firmware after adding new strings

---

## Related Documentation

- [CJK Font Support](./cjk-fonts.md) - External font installation
- [File Formats](./file-formats.md) - Binary file format specifications
- [Troubleshooting](./troubleshooting.md) - General troubleshooting guide