Xteink-X4-crosspoint-reader/docs/i18n.md

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:

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:

// 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

#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:

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

// 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

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:

   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:

   static const char* const STRINGS_KO[] = {
       // All strings translated to Korean
   };
   

3. Add to language arrays:

   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:

   // 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 - External font installation
• File Formats - Binary file format specifications
• Troubleshooting - General troubleshooting guide