@vielzeug/i18nit 1.1.3 → 1.2.0

package/README.md

@@ -1,36 +1,86 @@
 # @vielzeug/i18nit
 
-Type-safe, lightweight internationalization (i18n) library for TypeScript applications. Simple, powerful translation management with zero dependencies.
+## What is I18nit?
 
-## Features
+**I18nit** is a type-safe, lightweight internationalization library for TypeScript. Build multilingual applications with powerful pluralization, nested translations, and lazy loading—all in just 1.6 KB.
 
-- ✅ **Type-Safe** - Full TypeScript support with generic types
-- ✅ **Lightweight** - ~2.3KB gzipped with zero dependencies
-- ✅ **Universal Pluralization** - 100+ languages via Intl.PluralRules API
-- ✅ **Smart Array Handling** - Auto-join with separators, length access, and safe indexing
-- ✅ **Path Interpolation** - Support for nested objects and array indices
-- ✅ **Lazy Loading** - Async locale loading with automatic caching
-- ✅ **Namespaces** - Organize translations by feature or module
-- ✅ **Fallback Chain** - Multiple fallback locales with automatic language variants
-- ✅ **HTML Escaping** - Built-in XSS protection
-- ✅ **Number & Date Formatting** - Locale-aware formatting with Intl API
-- ✅ **Structured Errors** - Detailed error information with MissingVariableError
-- ✅ **Framework Agnostic** - Works with React, Vue, Svelte, or vanilla JS
+### The Problem
 
-## Installation
+Internationalization libraries are often heavy and complex:
+
+- **i18next** is feature-rich but adds 11KB+ to your bundle
+- **react-intl** is React-specific and requires setup
+- **FormatJS** has a steep learning curve
+- Manual translations lead to missing keys and runtime errors
+- Type safety requires extra tooling
+
+### The Solution
+
+I18nit provides a simple, type-safe API using native browser APIs:
+
+```typescript
+import { createI18n } from '@vielzeug/i18nit';
+
+const i18n = createI18n({
+  locale: 'en',
+  messages: {
+    en: {
+      welcome: 'Welcome, {name}!',
+      items: 'You have {count} item | You have {count} items',
+    },
+    es: {
+      welcome: '¡Bienvenido, {name}!',
+      items: 'Tienes {count} artículo | Tienes {count} artículos',
+    },
+  },
+});
+
+// Interpolation
+i18n.t('welcome', { name: 'Alice' }); // "Welcome, Alice!"
+
+// Automatic pluralization
+i18n.t('items', { count: 1 }); // "You have 1 item"
+i18n.t('items', { count: 5 }); // "You have 5 items"
+```
+
+## ✨ Features
+
+- ✅ **Type-Safe** – Full TypeScript support with generic types
+- ✅ **Lightweight** – 1.6 KB gzipped with zero dependencies
+- ✅ **Universal Pluralization** – 100+ languages via Intl.PluralRules API
+- ✅ **Smart Array Handling** – Auto-join with separators, length access, and safe indexing
+- ✅ **Path Interpolation** – Support for nested objects and array indices
+- ✅ **Lazy Loading** – Async locale loading with automatic caching
+- ✅ **Namespaces** – Organize translations by feature or module
+- ✅ **Fallback Chain** – Multiple fallback locales with automatic language variants
+- ✅ **HTML Escaping** – Built-in XSS protection
+- ✅ **Number & Date Formatting** – Locale-aware formatting with Intl API
+- ✅ **Framework Agnostic** – Works with React, Vue, Svelte, or vanilla JS
+
+## 🆚 Comparison with Alternatives
+
+| Feature             | I18nit         | i18next | react-intl | FormatJS     |
+| ------------------- | -------------- | ------- | ---------- | ------------ |
+| Bundle Size (gzip)  | **~1.6 KB**    | ~11KB   | ~14KB      | ~14KB        |
+| TypeScript Support  | ✅ First-class | ✅ Good | ✅ Good    | ✅ Excellent |
+| Pluralization       | ✅ Native Intl | ✅ ICU  | ✅ ICU     | ✅ ICU       |
+| Nested Translations | ✅ Built-in    | ✅ Yes  | ⚠️ Limited | ✅ Yes       |
+| Lazy Loading        | ✅ Async       | ✅ Yes  | ⚠️ Manual  | ✅ Yes       |
+| Framework Agnostic  | ✅ Yes         | ✅ Yes  | ❌ React   | ❌ React     |
+| Dependencies        | 0              | 3       | 5          | 7            |
+
+## 📦 Installation
 
 ```bash
 # pnpm
 pnpm add @vielzeug/i18nit
-
 # npm
 npm install @vielzeug/i18nit
-
 # yarn
 yarn add @vielzeug/i18nit
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
 ```typescript
 import { createI18n } from '@vielzeug/i18nit';
@@ -71,7 +121,7 @@ i18n.setLocale('es');
 i18n.t('greeting', { name: 'Mundo' }); // "¡Hola, Mundo!"
 ```
 
-## Core Concepts
+## 📚 Core Concepts
 
 ### Translation Keys
 
@@ -91,6 +141,52 @@ const i18n = createI18n({
 i18n.t('user.profile.title'); // "Profile"
 ```
 
+### Nested Message Objects
+
+You can organize messages using nested objects for better structure:
+
+```typescript
+const i18n = createI18n({
+  locale: 'en',
+  messages: {
+    en: {
+      // Flat structure
+      welcome: 'Welcome!',
+      
+      // Nested structure - access with dot notation
+      user: {
+        greeting: 'Hello, {name}!',
+        profile: {
+          title: 'User Profile',
+          settings: 'Profile Settings',
+        },
+      },
+      
+      // Deep nesting
+      app: {
+        navigation: {
+          menu: {
+            home: 'Home',
+            about: 'About',
+          },
+        },
+      },
+    },
+  },
+});
+
+// Access nested messages with dot notation
+i18n.t('welcome');                    // "Welcome!"
+i18n.t('user.greeting', { name: 'Alice' }); // "Hello, Alice!"
+i18n.t('user.profile.title');         // "User Profile"
+i18n.t('app.navigation.menu.home');   // "Home"
+
+// Use with namespaces for cleaner code
+const userNs = i18n.namespace('user');
+userNs.t('greeting', { name: 'Bob' }); // "Hello, Bob!"
+userNs.t('profile.title');             // "User Profile"
+```
+
 ### Variable Interpolation
 
 #### Basic Interpolation
@@ -138,7 +234,7 @@ const i18n = createI18n({
 i18n.t('shopping', { items: ['Apple', 'Banana', 'Orange'] });
 // "Shopping list: Apple, Banana, Orange"
 
-// Natural "and" lists (locale-aware via Intl.ListFormat - supports 100+ languages automatically)
+// Natural "and" lists (locale-aware via Intl.ListFormat – supports 100+ languages automatically)
 i18n.t('guests', { names: ['Alice'] });
 // "Invited: Alice"
 i18n.t('guests', { names: ['Alice', 'Bob'] });
@@ -146,7 +242,7 @@ i18n.t('guests', { names: ['Alice', 'Bob'] });
 i18n.t('guests', { names: ['Alice', 'Bob', 'Charlie'] });
 // "Invited: Alice, Bob, and Charlie" (Oxford comma in English)
 
-// Natural "or" lists (locale-aware via Intl.ListFormat - supports 100+ languages automatically)
+// Natural "or" lists (locale-aware via Intl.ListFormat – supports 100+ languages automatically)
 i18n.t('options', { choices: ['Tea', 'Coffee', 'Juice'] });
 // "Choose: Tea, Coffee, or Juice"
 
@@ -160,22 +256,25 @@ i18n.t('count', { items: ['A', 'B', 'C'] });
 ```
 
 **Array Features:**
-- `{items}` - Join with comma (`, `)
-- `{items|and}` - Natural "and" list with locale-aware conjunction (uses Intl.ListFormat - supports 100+ languages)
-- `{items|or}` - Natural "or" list with locale-aware conjunction (uses Intl.ListFormat - supports 100+ languages)
-- `{items| - }` - Custom separator (e.g., "A - B - C")
-- `{items.length}` - Array length
-- `{items[0]}` - Safe index access (returns empty if out of bounds)
+
+- `{items}` – Join with comma (`, `)
+- `{items|and}` – Natural "and" list with locale-aware conjunction (uses Intl.ListFormat – supports 100+ languages)
+- `{items|or}` – Natural "or" list with locale-aware conjunction (uses Intl.ListFormat – supports 100+ languages)
+- `{items| – }` – Custom separator (e.g., "A – B – C")
+- `{items.length}` – Array length
+- `{items[0]}` – Safe index access (returns empty if out of bounds)
 
 **Locale-Aware List Formatting:**  
 The `and` and `or` separators use the built-in **Intl.ListFormat API** which automatically handles:
-- **100+ languages** - Supports all languages available in the browser/runtime
-- **Proper grammar** - Oxford comma, locale-specific punctuation
-- **Right-to-left languages** - Arabic, Hebrew, etc.
-- **Unicode CLDR standards** - International standard for list formatting
-- **No manual configuration** - Zero maintenance required
+
+- **100+ languages** – Supports all languages available in the browser/runtime
+- **Proper grammar** – Oxford comma, locale-specific punctuation
+- **Right-to-left languages** – Arabic, Hebrew, etc.
+- **Unicode CLDR standards** – International standard for list formatting
+- **No manual configuration** – Zero maintenance required
 
 Examples across languages:
+
 - **English**: "A, B, and C" (with Oxford comma)
 - **Spanish**: "A, B y C" (uses "y")
 - **French**: "A, B et C" (uses "et")
@@ -186,55 +285,31 @@ Examples across languages:
 
 #### Supported Path Formats
 
-- `{name}` - Simple variable
-- `{user.name}` - Nested object property
-- `{items[0]}` - Array index (safe - returns empty if out of bounds)
-- `{items}` - Array join with default separator
-- `{items|and}` - Array join with "and"
-- `{items.length}` - Array length
-- `{data.items[0].value}` - Mixed notation
+- `{name}` – Simple variable
+- `{user.name}` – Nested object property
+- `{items[0]}` – Array index (safe – returns empty if out of bounds)
+- `{items}` – Array join with default separator
+- `{items|and}` – Array join with "and"
+- `{items.length}` – Array length
+- `{data.items[0].value}` – Mixed notation
 
 **Limitations:**
+
 - Only numeric bracket notation `[0]`, `[123]`
 - Quoted keys not supported `["key"]`
 - Non-numeric brackets not supported `[key]`
 
 ### Missing Variable Handling
 
-Control how missing variables are handled:
+Missing variables are automatically replaced with empty strings:
 
 ```typescript
-// Empty string (default)
-const i18n1 = createI18n({
-  messages: { en: { msg: 'Hello, {name}!' } },
-  missingVar: 'empty',
-});
-i18n1.t('msg'); // "Hello, !"
-
-// Preserve placeholder
-const i18n2 = createI18n({
-  messages: { en: { msg: 'Hello, {name}!' } },
-  missingVar: 'preserve',
-});
-i18n2.t('msg'); // "Hello, {name}!"
-
-// Throw error
-import { MissingVariableError } from '@vielzeug/i18nit';
-
-const i18n3 = createI18n({
+const i18n = createI18n({
   messages: { en: { msg: 'Hello, {name}!' } },
-  missingVar: 'error',
 });
 
-try {
-  i18n3.t('msg');
-} catch (error) {
-  if (error instanceof MissingVariableError) {
-    console.log(error.key);      // 'msg'
-    console.log(error.variable); // 'name'
-    console.log(error.locale);   // 'en'
-  }
-}
+i18n.t('msg'); // "Hello, !"
+i18n.t('msg', { name: 'Alice' }); // "Hello, Alice!"
 ```
 
 ### Pluralization
@@ -274,40 +349,7 @@ i18nit uses the browser's built-in `Intl.PluralRules` API to automatically suppo
 - **Japanese (ja)**: other
 - And 90+ more languages...
 
-### Message Functions
-
-For complex dynamic content, use function-based messages:
-
-```typescript
-const i18n = createI18n({
-  locale: 'en',
-  messages: {
-    en: {
-      // Simple function
-      dynamic: (vars) => `Hello, ${vars.name}!`,
-
-      // With number formatting
-      price: (vars, helpers) => 
-        `Price: ${helpers.number(vars.amount as number, { 
-          style: 'currency', 
-          currency: 'USD' 
-        })}`,
-
-      // With date formatting
-      event: (vars, helpers) => 
-        `Event on ${helpers.date(vars.date as Date, { 
-          dateStyle: 'long' 
-        })}`,
-    },
-  },
-});
-
-i18n.t('dynamic', { name: 'Eve' }); // "Hello, Eve!"
-i18n.t('price', { amount: 99.99 }); // "Price: $99.99"
-i18n.t('event', { date: new Date('2024-01-15') }); // "Event on January 15, 2024"
-```
-
-## Advanced Features
+## 🔥 Advanced Features
 
 ### Fallback Locales
 
@@ -330,6 +372,7 @@ i18n.t('welcome'); // "Welcome!" (en fallback)
 ```
 
 **Fallback Chain:**
+
 1. Primary locale (e.g., `de-CH`)
 2. Base language (e.g., `de` from `de-CH`)
 3. First fallback locale
@@ -338,39 +381,64 @@ i18n.t('welcome'); // "Welcome!" (en fallback)
 
 ### Async Locale Loading
 
-Load translations on-demand for better performance:
+Load translations on-demand for better performance. Loaders receive the locale as a parameter, allowing you to reuse a single function:
 
 ```typescript
+// Define a reusable loader function
+const loadLocale = async (locale: string) => {
+  const response = await fetch(`/locales/${locale}.json`);
+  return response.json();
+};
+
 const i18n = createI18n({
   locale: 'en',
   loaders: {
-    fr: async () => {
-      const response = await fetch('/locales/fr.json');
-      return response.json();
-    },
-    de: async () => import('./locales/de.json'),
+    fr: loadLocale,  // Loader receives 'fr' as parameter
+    de: loadLocale,  // Loader receives 'de' as parameter
+    es: loadLocale,  // Loader receives 'es' as parameter
   },
 });
 
-// Lazy translation - loads locale first
-const text = await i18n.tl('greeting', { name: 'World' }, { locale: 'fr' });
+// Load a locale before using it
+await i18n.load('fr');
+i18n.setLocale('fr');
+i18n.t('greeting'); // Uses loaded French messages
+
+// Or use dynamic imports
+const importLoader = async (locale: string) => {
+  const module = await import(`./locales/${locale}.json`);
+  return module.default;
+};
+
+i18n.register('it', importLoader);
+await i18n.load('it');
+```
+
+// Preload at app startup
+await i18n.loadAll(['en', 'fr', 'de']);
 
 // Or load explicitly
-await i18n.load('de');
-i18n.t('greeting', undefined, { locale: 'de' });
+await i18n.load('fr');
+i18n.setLocale('fr');
+i18n.t('greeting'); // Now uses French
 
 // Register loader dynamically
 i18n.register('es', async () => {
   const module = await import('./locales/es.json');
   return module.default;
 });
+
+// Load and use
+await i18n.load('es');
+i18n.t('greeting', undefined, { locale: 'es' });
 ```
 
 **Features:**
+
 - Concurrent requests are deduplicated
-- Failed loads can be retried
-- Errors are logged but don't break fallback
+- Failed loads throw errors (can be caught)
 - Locale is cached after loading
+- Use `loadAll()` to preload multiple locales at once
 
 ### Namespaces
 
@@ -404,7 +472,7 @@ Protect against XSS attacks with automatic HTML escaping:
 ```typescript
 const i18n = createI18n({
   messages: {
-    en: { 
+    en: {
       userContent: 'Comment: {content}',
     },
   },
@@ -416,14 +484,11 @@ const safeI18n = createI18n({
   messages: { en: { html: '<script>alert("xss")</script>' } },
 });
 
-safeI18n.t('html'); 
+safeI18n.t('html');
 // "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
 
 // Or per translation
-i18n.t('userContent', 
-  { content: '<b>Bold</b>' }, 
-  { escape: true }
-);
+i18n.t('userContent', { content: '<b>Bold</b>' }, { escape: true });
 // "Comment: &lt;b&gt;Bold&lt;/b&gt;"
 ```
 
@@ -473,27 +538,13 @@ unsubscribe();
 ```
 
 **Use Cases:**
+
 - Update UI when locale changes
 - Reload locale-specific data
 - Analytics/tracking
 - State management integration
 
-### Custom Missing Key Handler
-
-Customize behavior for missing translations:
-
-```typescript
-const i18n = createI18n({
-  missingKey: (key, locale) => {
-    console.warn(`Missing translation: ${key} in ${locale}`);
-    return `[${locale}:${key}]`;
-  },
-});
-
-i18n.t('nonexistent.key'); // "[en:nonexistent.key]"
-```
-
-## API Reference
+### Subscriptions
 
 ### createI18n(config?)
 
@@ -501,13 +552,11 @@ Creates a new i18n instance.
 
 ```typescript
 type I18nConfig = {
-  locale?: string;                    // Default: 'en'
-  fallback?: string | string[];       // Fallback locale(s)
+  locale?: string; // Default: 'en'
+  fallback?: string | string[]; // Fallback locale(s)
   messages?: Record<string, Messages>; // Initial translations
   loaders?: Record<string, () => Promise<Messages>>; // Async loaders
-  escape?: boolean;                   // Global HTML escaping (default: false)
-  missingKey?: (key: string, locale: string) => string; // Missing key handler
-  missingVar?: 'preserve' | 'empty' | 'error'; // Missing variable strategy
+  escape?: boolean; // Global HTML escaping (default: false)
 };
 ```
 
@@ -524,26 +573,18 @@ i18n.t('greeting', { name: 'Bob' }, { locale: 'fr', escape: true }); // With opt
 ```
 
 **Options:**
-- `locale?: string` - Override locale for this translation
-- `fallback?: string` - Custom fallback text
-- `escape?: boolean` - Override HTML escaping
 
-#### `tl(key, vars?, options?)`
-
-Translate a key asynchronously (loads locale if needed).
-
-```typescript
-await i18n.tl('greeting', { name: 'Alice' }, { locale: 'fr' });
-```
+- `locale?: string` – Override locale for this translation
+- `escape?: boolean` – Override HTML escaping
 
 ### Locale Management
 
 ```typescript
-i18n.setLocale('fr');           // Change locale
-i18n.getLocale();               // Get current locale
-i18n.hasLocale('es');           // Check if locale exists
-i18n.has('key');                // Check if key exists
-i18n.has('key', 'fr');          // Check if key exists in locale
+i18n.setLocale('fr'); // Change locale
+i18n.getLocale(); // Get current locale
+i18n.hasLocale('es'); // Check if locale exists
+i18n.has('key'); // Check if key exists
+i18n.has('key', 'fr'); // Check if key exists in locale
 await i18n.hasAsync('key', 'es'); // Check with async loading
 ```
 
@@ -582,7 +623,6 @@ i18n.date(value, options?, locale?);
 ```typescript
 const ns = i18n.namespace('auth');
 ns.t('login.title');
-await ns.tl('register.title', undefined, { locale: 'fr' });
 ```
 
 ### Subscriptions
@@ -611,11 +651,7 @@ export function I18nProvider({ children, config }) {
     return i18n.subscribe(setLocale);
   }, [i18n]);
 
-  return (
-    <I18nContext.Provider value={{ i18n, locale }}>
-      {children}
-    </I18nContext.Provider>
-  );
+  return <I18nContext.Provider value={{ i18n, locale }}>{children}</I18nContext.Provider>;
 }
 
 export function useI18n() {
@@ -627,10 +663,9 @@ export function useI18n() {
 export function useTranslation(namespace?: string) {
   const { i18n } = useI18n();
   const ns = namespace ? i18n.namespace(namespace) : i18n;
-  
+
   return {
     t: ns.t.bind(ns),
-    tl: ns.tl.bind(ns),
     locale: i18n.getLocale(),
     setLocale: i18n.setLocale.bind(i18n),
   };
@@ -639,7 +674,7 @@ export function useTranslation(namespace?: string) {
 // Usage
 function MyComponent() {
   const { t, locale, setLocale } = useTranslation('dashboard');
-  
+
   return (
     <div>
       <h1>{t('welcome')}</h1>
@@ -666,7 +701,7 @@ export const i18nPlugin: Plugin = {
   install(app) {
     app.config.globalProperties.$t = i18n.t.bind(i18n);
     app.config.globalProperties.$i18n = i18n;
-    
+
     app.provide('i18n', i18n);
     app.provide('locale', locale);
   },
@@ -676,7 +711,6 @@ export const i18nPlugin: Plugin = {
 export function useI18n() {
   return {
     t: i18n.t.bind(i18n),
-    tl: i18n.tl.bind(i18n),
     locale,
     setLocale: (newLocale: string) => i18n.setLocale(newLocale),
   };
@@ -758,40 +792,13 @@ const i18n = createI18n({
 ### 4. Type-Safe Translation Keys
 
 ```typescript
-type TranslationKeys = 
-  | 'auth.login.title'
-  | 'auth.register.title'
-  | 'dashboard.welcome';
+type TranslationKeys = 'auth.login.title' | 'auth.register.title' | 'dashboard.welcome';
 
 function t(key: TranslationKeys, vars?: Record<string, unknown>) {
   return i18n.t(key, vars);
 }
 ```
 
-### 5. Use Structured Error Handling
-
-```typescript
-import { MissingVariableError } from '@vielzeug/i18nit';
-
-const i18n = createI18n({
-  missingVar: 'error',
-  messages: { en: { greeting: 'Hello, {name}!' } },
-});
-
-try {
-  i18n.t('greeting');
-} catch (error) {
-  if (error instanceof MissingVariableError) {
-    // Log to error tracking service
-    console.error('Missing variable:', {
-      key: error.key,
-      variable: error.variable,
-      locale: error.locale,
-    });
-  }
-}
-```
-
 ## TypeScript Support
 
 Full TypeScript support with type inference:
@@ -822,33 +829,28 @@ const config: I18nConfig = {
 const i18n = createI18n(config);
 ```
 
-## Comparison
+## 📖 Documentation
 
-| Feature | i18nit | i18next | react-intl |
-|---------|--------|---------|------------|
-| Bundle Size | **~3KB** | ~12KB | ~15KB |
-| Dependencies | **0** | 2+ | 10+ |
-| TypeScript | ✅ First-class | ✅ Good | ✅ Good |
-| Pluralization | ✅ Built-in | ✅ Plugin | ✅ Built-in |
-| Async Loading | ✅ Built-in | ✅ Built-in | ⚠️ Manual |
-| Path Interpolation | ✅ `{user.name}` | ❌ | ❌ |
-| Message Functions | ✅ Built-in | ⚠️ Limited | ✅ Components |
-| HTML Escaping | ✅ Built-in | ⚠️ Manual | ✅ Built-in |
-| Structured Errors | ✅ MissingVariableError | ❌ | ❌ |
-| Framework Agnostic | ✅ | ✅ | ❌ React only |
+- [**Full Documentation**](https://helmuthdu.github.io/vielzeug/i18nit)
+- [**Usage Guide**](https://helmuthdu.github.io/vielzeug/i18nit/usage)
+- [**API Reference**](https://helmuthdu.github.io/vielzeug/i18nit/api)
+- [**Examples**](https://helmuthdu.github.io/vielzeug/i18nit/examples)
 
-## License
+## 📄 License
 
 MIT © [Helmuth Saatkamp](https://github.com/helmuthdu)
 
-## Links
+## 🤝 Contributing
+
+Contributions are welcome! Check our [GitHub repository](https://github.com/helmuthdu/vielzeug).
+
+## 🔗 Links
 
 - [GitHub Repository](https://github.com/helmuthdu/vielzeug)
-- [Documentation](https://vielzeug.dev)
-- [NPM Package](https://www.npmjs.com/package/@vielzeug/i18nit)
+- [Documentation](https://helmuthdu.github.io/vielzeug/deposit)
+- [NPM Package](https://www.npmjs.com/package/@vielzeug/deposit)
 - [Issue Tracker](https://github.com/helmuthdu/vielzeug/issues)
 
 ---
 
-Part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) ecosystem - A collection of type-safe utilities for modern web development.
-
+Part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) ecosystem – A collection of type-safe utilities for modern web development.