simplified-i18n

A simplified internationalization (i18n) management package for JavaScript and TypeScript projects.

Features

• Simple and intuitive API for managing translations
• Support for multiple languages
• Interpolation of variables in translations
• Pluralization support
• Date and number formatting
• Lazy loading of translations
• TypeScript support

Installation

You can install simplified-i18n using npm:

npm install simplified-i18n

Or using yarn:

yarn add simplified-i18n

Usage

Basic Usage

import { I18n } from 'simplified-i18n';

const i18n = new I18n({
  defaultLanguage: 'en',
  fallbackLanguage: 'en',
  loadPath: './locales',
});

// Basic translation
console.log(i18n.translate('greeting')); // Output: "Hello"

// Translation with language specification
console.log(i18n.translate('greeting', 'fr')); // Output: "Bonjour"

// Translation with interpolation
console.log(i18n.translate('welcome', 'en', { name: 'John' })); // Output: "Welcome, John!"

Pluralization

const count = 5;
console.log(i18n.pluralize('items', { count })); // Output: "You have 5 items"

Date Formatting

const date = new Date('2023-01-01');
console.log(i18n.formatDate(date, { year: 'numeric', month: 'long', day: 'numeric' }));
// Output: "January 1, 2023"

Number Formatting

console.log(i18n.formatNumber(1234.56, { style: 'currency', currency: 'USD' }));
// Output: "$1,234.56"

API Reference

Constructor

new I18n(options: I18nOptions)

• options.defaultLanguage: The default language to use for translations.
• options.fallbackLanguage: The language to use when a translation is missing in the requested language.
• options.loadPath: The path to the directory containing translation files.

Adding Locales

Locales are added as JSON files in a directory specified by the loadPath option when initializing the I18n instance. Here's how to structure your locales:

1. Create a directory for your locales (e.g., locales/).
2. For each language, create a JSON file named with the language code (e.g., en.json, fr.json).
3. In each JSON file, define your translations as key-value pairs.

Example directory structure:

project-root/
├── locales/
│   ├── en.json
│   ├── fr.json
│   └── es.json
├── src/
│   └── index.ts
└── package.json

Example content of en.json:

{
  "greeting": "Hello",
  "welcome": "Welcome, {{name}}!",
  "items": {
    "one": "You have {{count}} item",
    "other": "You have {{count}} items"
  }
}

Example content of fr.json:

{
  "greeting": "Bonjour",
  "welcome": "Bienvenue, {{name}} !",
  "items": {
    "one": "Vous avez {{count}} article",
    "other": "Vous avez {{count}} articles"
  }
}

Loading Locales

When initializing the I18n instance, specify the path to your locales directory:

import { I18n } from 'simplified-i18n';
import path from 'path';

const i18n = new I18n({
  defaultLanguage: 'en',
  fallbackLanguage: 'en',
  loadPath: path.join(__dirname, 'locales'),
});

This will automatically load all JSON files in the specified directory as language files.

Adding Translations Programmatically

You can also add translations programmatically using the addTranslation method:

i18n.addTranslation('en', 'newKey', 'New translation');

Loading Remote Translations

For dynamic loading of translations, use the loadRemoteTranslations method:

await i18n.loadRemoteTranslations('https://api.example.com/translations/de.json', 'de');

This will fetch the translations from the specified URL and add them for the 'de' language.

Methods

• translate(key: string, lang?: string, params?: object): string
• pluralize(key: string, options: PluralizeOptions): string
• formatDate(date: Date, options?: Intl.DateTimeFormatOptions, lang?: string): string
• formatNumber(number: number, options?: Intl.NumberFormatOptions, lang?: string): string
• setLanguage(lang: string): void
• addTranslation(lang: string, key: string, value: string): void
• loadRemoteTranslations(url: string, lang: string): Promise<void>

Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you have any questions or run into any issues, please open an issue on the GitHub repository.

Acknowledgements

• Intl.PluralRules
• Intl.DateTimeFormat
• Intl.NumberFormat