@kiro/i18n

Lightweight, type-safe internationalization (i18n) library with comprehensive property-based testing. Built for modern TypeScript applications with a focus on reliability and developer experience.

✨ Features

• 🌍 Multi-language Support: Built-in support for English, Simplified Chinese, and Traditional Chinese
• 📦 Modular Architecture: Organized translation files by feature (menu, settings, commands, etc.)
• 🔒 Type-Safe: Full TypeScript support with comprehensive type definitions
• 🚀 Performance Optimized: In-memory caching and lazy loading
• 🎯 Text Interpolation: Dynamic content with {{variable}} syntax
• 🔄 Graceful Fallback: Automatic fallback to default language when translations are missing
• 💾 Persistent Preferences: Save and restore user language preferences
• 🧪 Property-Based Testing: Comprehensive test coverage using fast-check
• 📝 BCP 47 Compliant: Standard language codes (e.g., "zh-CN", "en-US")

📦 Installation

npm install @kiro/i18n

🚀 Quick Start

import { getI18nAPI } from '@kiro/i18n';

// Initialize the i18n system
const i18n = getI18nAPI({
  localesPath: './locales',
  defaultLanguage: 'en-US',
  fallbackLanguage: 'en-US'
});

await i18n.initialize();

// Translate a key
const greeting = i18n.t('common.hello'); // "Hello"

// Translate with interpolation
const welcome = i18n.t('common.welcome', { name: 'Alice' }); // "Welcome Alice"

// Change language
await i18n.changeLanguage('zh-CN');
const greetingCN = i18n.t('common.hello'); // "你好"

// Listen to language changes
i18n.onLanguageChange((newLanguage) => {
  console.log(`Language changed to: ${newLanguage}`);
});

📁 Project Structure

your-project/
├── locales/
│   ├── languages.json            # Language metadata
│   ├── en-US/                    # English translations
│   │   ├── common.json
│   │   ├── menu.json
│   │   └── settings.json
│   └── zh-CN/                    # Simplified Chinese translations
│       ├── common.json
│       ├── menu.json
│       └── settings.json
└── src/
    └── index.ts

📝 Translation File Format

Translation files use nested JSON structure:

{
  "menu": {
    "file": {
      "label": "文件",
      "open": "打开",
      "save": "保存"
    }
  },
  "common": {
    "welcome": "欢迎 {{name}}"
  }
}

Access translations using dot-separated keys: menu.file.open

🔧 API Reference

getI18nAPI(config?: I18nConfig): I18nAPI

Get the singleton instance of the i18n API.

Config Options:

• localesPath: Path to translation files (default: 'locales')
• defaultLanguage: Default language code (default: 'en-US')
• fallbackLanguage: Fallback language code (default: 'en-US')

I18nAPI Methods

initialize(): Promise<void>

Initialize the i18n system and load the default language.

t(key: string, params?: Record<string, string>): string

Translate a key with optional parameter interpolation.

changeLanguage(languageCode: LanguageCode): Promise<void>

Change the current language.

getCurrentLanguage(): LanguageCode

Get the current language code.

getSupportedLanguages(): LanguageInfo[]

Get list of all supported languages.

onLanguageChange(callback: (language: LanguageCode) => void): () => void

Register a callback for language changes. Returns an unsubscribe function.

🧪 Testing

The library includes comprehensive test coverage with both unit tests and property-based tests:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Generate coverage report
npm run test:coverage

🏗️ Building

# Build for production
npm run build

# Build and watch for changes
npm run dev

# Type check
npm run lint

📄 Language Metadata

Define supported languages in locales/languages.json:

{
  "languages": [
    {
      "code": "en-US",
      "name": "English",
      "nativeName": "English"
    },
    {
      "code": "zh-CN",
      "name": "Simplified Chinese",
      "nativeName": "简体中文"
    }
  ]
}

🎯 Use Cases

• Desktop applications (Electron, Tauri)
• Web applications (React, Vue, Angular)
• CLI tools
• VS Code extensions
• Any TypeScript/JavaScript project requiring i18n

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📜 License

MIT © Kiro Team

🔗 Links

• GitHub Repository
• Issue Tracker
• npm Package

🙏 Acknowledgments

Built with:

• TypeScript
• Vitest
• fast-check for property-based testing