@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

``bash
npm install @kiro/i18n
`

🚀 Quick Start

`typescript
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:

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

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

🔧 API Reference

$3

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')

$3

#### initialize(): Promise
Initialize the i18n system and load the default language.

#### t(key: string, params?: Record): string
Translate a key with optional parameter interpolation.

#### changeLanguage(languageCode: LanguageCode): Promise
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:

`bash

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

`bash

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:

`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