@vielzeug/i18nit 1.2.0 → 2.1.0

package/README.md

@@ -1,856 +1,84 @@
 # @vielzeug/i18nit
 
-## What is I18nit?
+> Lightweight, type-safe i18n with nested keys, lazy loaders, interpolation, pluralization, and reactive subscriptions.
 
-**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.
+[![npm version](https://img.shields.io/npm/v/@vielzeug/i18nit)](https://www.npmjs.com/package/@vielzeug/i18nit) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-### The Problem
+`@vielzeug/i18nit` is a zero-dependency internationalization library for TypeScript. It combines typed key paths, fallback locale chains, async locale loading, and Intl formatting helpers.
 
-Internationalization libraries are often heavy and complex:
+## Installation
 
-- **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"
+```sh
+pnpm add @vielzeug/i18nit
+# npm install @vielzeug/i18nit
+# yarn add @vielzeug/i18nit
 ```
 
-## ✨ 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
+## Entry Points
 
-| 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            |
+| Entry | Purpose |
+| --- | --- |
+| `@vielzeug/i18nit` | Main API (`createI18n`, exported types) |
+| `@vielzeug/i18nit/core` | Core bundle entry |
 
-## 📦 Installation
+## Quick Start
 
-```bash
-# pnpm
-pnpm add @vielzeug/i18nit
-# npm
-npm install @vielzeug/i18nit
-# yarn
-yarn add @vielzeug/i18nit
-```
-
-## 🚀 Quick Start
-
-```typescript
+```ts
 import { createI18n } from '@vielzeug/i18nit';
 
-// Create instance with messages
 const i18n = createI18n({
+  fallback: 'en',
   locale: 'en',
   messages: {
-    en: {
-      greeting: 'Hello, {name}!',
-      items: {
-        zero: 'No items',
-        one: 'One item',
-        other: '{count} items',
-      },
-    },
-    es: {
-      greeting: '¡Hola, {name}!',
-      items: {
-        zero: 'Sin artículos',
-        one: 'Un artículo',
-        other: '{count} artículos',
-      },
-    },
-  },
-});
-
-// Simple translation
-i18n.t('greeting', { name: 'World' }); // "Hello, World!"
-
-// Pluralization
-i18n.t('items', { count: 0 }); // "No items"
-i18n.t('items', { count: 1 }); // "One item"
-i18n.t('items', { count: 5 }); // "5 items"
-
-// Change locale
-i18n.setLocale('es');
-i18n.t('greeting', { name: 'Mundo' }); // "¡Hola, Mundo!"
-```
-
-## 📚 Core Concepts
-
-### Translation Keys
-
-Translation keys support dot notation for nested organization:
-
-```typescript
-const i18n = createI18n({
-  messages: {
-    en: {
-      'user.profile.title': 'Profile',
-      'user.settings.title': 'Settings',
-      'admin.dashboard': 'Dashboard',
+    de: {
+      greeting: 'Hallo, {name}!',
+      inbox: { one: 'Eine Nachricht', other: '{count} Nachrichten' },
     },
-  },
-});
-
-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',
-          },
-        },
-      },
+      greeting: 'Hello, {name}!',
+      inbox: { zero: 'No messages', one: 'One message', other: '{count} messages' },
+      nav: { home: 'Home' },
     },
   },
 });
 
-// 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
-
-```typescript
 i18n.t('greeting', { name: 'Alice' });
-// Template: "Hello, {name}!"
-// Result: "Hello, Alice!"
-```
-
-#### Nested Object Access
-
-```typescript
-i18n.t('message', { user: { name: 'Bob', role: 'Admin' } });
-// Template: "User {user.name} is {user.role}"
-// Result: "User Bob is Admin"
-```
-
-#### Array Index Access
-
-```typescript
-i18n.t('friends', { friends: [{ name: 'Charlie' }, { name: 'Dave' }] });
-// Template: "First friend: {friends[0].name}"
-// Result: "First friend: Charlie"
-```
-
-#### Array Handling
-
-Arrays can be intelligently formatted with various separators:
-
-```typescript
-const i18n = createI18n({
-  messages: {
-    en: {
-      shopping: 'Shopping list: {items}',
-      guests: 'Invited: {names|and}',
-      options: 'Choose: {choices|or}',
-      path: 'Path: {folders| / }',
-      count: 'You have {items.length} items',
-    },
-  },
-});
-
-// Default comma separator
-i18n.t('shopping', { items: ['Apple', 'Banana', 'Orange'] });
-// "Shopping list: Apple, Banana, Orange"
-
-// 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'] });
-// "Invited: Alice and 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)
-i18n.t('options', { choices: ['Tea', 'Coffee', 'Juice'] });
-// "Choose: Tea, Coffee, or Juice"
-
-// Custom separators
-i18n.t('path', { folders: ['home', 'user', 'documents'] });
-// "Path: home / user / documents"
-
-// Array length
-i18n.t('count', { items: ['A', 'B', 'C'] });
-// "You have 3 items"
-```
-
-**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)
-
-**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
-
-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")
-- **German**: "A, B und C" (uses "und")
-- **Japanese**: "A、B、C" (uses Japanese comma)
-- **Arabic**: Proper RTL formatting with "و"
-- And 90+ more languages automatically!
-
-#### 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
-
-**Limitations:**
-
-- Only numeric bracket notation `[0]`, `[123]`
-- Quoted keys not supported `["key"]`
-- Non-numeric brackets not supported `[key]`
-
-### Missing Variable Handling
-
-Missing variables are automatically replaced with empty strings:
-
-```typescript
-const i18n = createI18n({
-  messages: { en: { msg: 'Hello, {name}!' } },
-});
-
-i18n.t('msg'); // "Hello, !"
-i18n.t('msg', { name: 'Alice' }); // "Hello, Alice!"
-```
-
-### Pluralization
-
-Support for multiple plural forms based on locale-specific rules:
-
-```typescript
-const i18n = createI18n({
-  locale: 'en',
-  messages: {
-    en: {
-      notifications: {
-        zero: 'No notifications',
-        one: 'One notification',
-        other: '{count} notifications',
-      },
-    },
-  },
-});
-
-i18n.t('notifications', { count: 0 }); // "No notifications"
-i18n.t('notifications', { count: 1 }); // "One notification"
-i18n.t('notifications', { count: 5 }); // "5 notifications"
-```
-
-#### Supported Plural Rules
-
-i18nit uses the browser's built-in `Intl.PluralRules` API to automatically support pluralization for **100+ languages**, including:
-
-- **English (en)**: one, other
-- **French (fr)**: one (0-1), other
-- **Arabic (ar)**: zero, one, two, few, many, other
-- **Polish (pl)**: one, few, many
-- **Russian (ru)**: one, few, many, other
-- **German (de)**: one, other
-- **Chinese (zh)**: other
-- **Japanese (ja)**: other
-- And 90+ more languages...
-
-## 🔥 Advanced Features
-
-### Fallback Locales
-
-Define fallback locales for missing translations:
-
-```typescript
-const i18n = createI18n({
-  locale: 'de-CH',
-  fallback: ['de', 'en'],
-  messages: {
-    'de-CH': { greeting: 'Grüezi!' },
-    de: { greeting: 'Hallo!', goodbye: 'Auf Wiedersehen!' },
-    en: { greeting: 'Hello!', goodbye: 'Goodbye!', welcome: 'Welcome!' },
-  },
-});
-
-i18n.t('greeting'); // "Grüezi!" (de-CH)
-i18n.t('goodbye'); // "Auf Wiedersehen!" (de fallback)
-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
-4. Base of first fallback
-5. Continue through all fallbacks
-
-### Async Locale Loading
-
-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: loadLocale,  // Loader receives 'fr' as parameter
-    de: loadLocale,  // Loader receives 'de' as parameter
-    es: loadLocale,  // Loader receives 'es' as parameter
-  },
-});
-
-// 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('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 throw errors (can be caught)
-- Locale is cached after loading
-- Use `loadAll()` to preload multiple locales at once
-
-### Namespaces
-
-Organize translations by feature or module:
+i18n.t('inbox', { count: 0 });
+i18n.t('inbox', { count: 3 });
 
-```typescript
-const i18n = createI18n({
-  messages: {
-    en: {
-      'auth.login.title': 'Login',
-      'auth.login.button': 'Sign In',
-      'auth.register.title': 'Register',
-      'dashboard.welcome': 'Welcome back!',
-    },
-  },
-});
-
-// Create namespaced translator
-const auth = i18n.namespace('auth.login');
-auth.t('title'); // "Login"
-auth.t('button'); // "Sign In"
-
-const dashboard = i18n.namespace('dashboard');
-dashboard.t('welcome'); // "Welcome back!"
-```
-
-### HTML Escaping
-
-Protect against XSS attacks with automatic HTML escaping:
-
-```typescript
-const i18n = createI18n({
-  messages: {
-    en: {
-      userContent: 'Comment: {content}',
-    },
-  },
-});
-
-// Enable escaping globally
-const safeI18n = createI18n({
-  escape: true,
-  messages: { en: { html: '<script>alert("xss")</script>' } },
-});
-
-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 });
-// "Comment: &lt;b&gt;Bold&lt;/b&gt;"
-```
-
-### Number & Date Formatting
-
-Locale-aware formatting using the Intl API:
-
-```typescript
-const i18n = createI18n({ locale: 'en-US' });
-
-// Number formatting
-i18n.number(1234.56); // "1,234.56"
-i18n.number(99.99, { style: 'currency', currency: 'USD' }); // "$99.99"
-i18n.number(0.15, { style: 'percent' }); // "15%"
-
-// Date formatting
-const date = new Date('2024-01-15');
-i18n.date(date); // "1/15/2024"
-i18n.date(date, { dateStyle: 'long' }); // "January 15, 2024"
-i18n.date(date, { timeStyle: 'short' }); // "12:00 AM"
-
-// Timestamps
-i18n.date(Date.now(), { dateStyle: 'medium' }); // "Jan 15, 2024"
-
-// Custom locale
-i18n.number(1234.56, undefined, 'de-DE'); // "1.234,56"
-i18n.date(date, { dateStyle: 'short' }, 'fr'); // "15/01/2024"
-```
-
-### Subscriptions
-
-React to locale changes:
-
-```typescript
-const i18n = createI18n({ locale: 'en' });
-
-// Subscribe to locale changes
-const unsubscribe = i18n.subscribe((locale) => {
-  console.log('Locale changed to:', locale);
-  // Update UI, reload data, etc.
-});
-
-i18n.setLocale('fr'); // Logs: "Locale changed to: fr"
-
-// Unsubscribe when done
-unsubscribe();
-```
-
-**Use Cases:**
-
-- Update UI when locale changes
-- Reload locale-specific data
-- Analytics/tracking
-- State management integration
-
-### Subscriptions
-
-### createI18n(config?)
-
-Creates a new i18n instance.
-
-```typescript
-type I18nConfig = {
-  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)
-};
-```
-
-### Translation Methods
-
-#### `t(key, vars?, options?)`
-
-Translate a key synchronously.
-
-```typescript
-i18n.t('greeting'); // Simple
-i18n.t('greeting', { name: 'Alice' }); // With variables
-i18n.t('greeting', { name: 'Bob' }, { locale: 'fr', escape: true }); // With options
-```
-
-**Options:**
-
-- `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
-await i18n.hasAsync('key', 'es'); // Check with async loading
-```
-
-### Message Management
-
-```typescript
-// Add messages (merge)
-i18n.add('en', { newKey: 'New value' });
-
-// Set messages (replace)
-i18n.set('en', { key: 'Value' });
-
-// Get messages for locale
-const messages = i18n.getMessages('en');
-```
-
-### Async Loading
-
-```typescript
-// Register loader
-i18n.register('de', async () => import('./locales/de.json'));
-
-// Load locale
-await i18n.load('de');
+await i18n.switchLocale('de');
+i18n.t('nav.home'); // falls back to en
 ```
 
-### Formatting
-
-```typescript
-i18n.number(value, options?, locale?);
-i18n.date(value, options?, locale?);
-```
-
-### Namespace
-
-```typescript
-const ns = i18n.namespace('auth');
-ns.t('login.title');
-```
-
-### Subscriptions
-
-```typescript
-const unsubscribe = i18n.subscribe((locale) => {
-  console.log('Locale changed:', locale);
-});
-```
-
-## Framework Integration
-
-### React
-
-```tsx
-import { createI18n } from '@vielzeug/i18nit';
-import { createContext, useContext, useState, useEffect } from 'react';
-
-const I18nContext = createContext(null);
-
-export function I18nProvider({ children, config }) {
-  const [i18n] = useState(() => createI18n(config));
-  const [locale, setLocale] = useState(i18n.getLocale());
-
-  useEffect(() => {
-    return i18n.subscribe(setLocale);
-  }, [i18n]);
-
-  return <I18nContext.Provider value={{ i18n, locale }}>{children}</I18nContext.Provider>;
-}
-
-export function useI18n() {
-  const context = useContext(I18nContext);
-  if (!context) throw new Error('useI18n must be used within I18nProvider');
-  return context;
-}
-
-export function useTranslation(namespace?: string) {
-  const { i18n } = useI18n();
-  const ns = namespace ? i18n.namespace(namespace) : i18n;
-
-  return {
-    t: ns.t.bind(ns),
-    locale: i18n.getLocale(),
-    setLocale: i18n.setLocale.bind(i18n),
-  };
-}
-
-// Usage
-function MyComponent() {
-  const { t, locale, setLocale } = useTranslation('dashboard');
-
-  return (
-    <div>
-      <h1>{t('welcome')}</h1>
-      <button onClick={() => setLocale('fr')}>Français</button>
-    </div>
-  );
-}
-```
-
-### Vue 3
-
-```typescript
-import { createI18n } from '@vielzeug/i18nit';
-import { ref, onUnmounted, Plugin } from 'vue';
-
-const i18n = createI18n({ locale: 'en' });
-const locale = ref(i18n.getLocale());
-
-const unsubscribe = i18n.subscribe((newLocale) => {
-  locale.value = newLocale;
-});
-
-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);
-  },
-};
-
-// Composable
-export function useI18n() {
-  return {
-    t: i18n.t.bind(i18n),
-    locale,
-    setLocale: (newLocale: string) => i18n.setLocale(newLocale),
-  };
-}
-
-// Usage in component
-<script setup>
-import { useI18n } from './i18n';
-
-const { t, locale, setLocale } = useI18n();
-</script>
-
-<template>
-  <div>
-    <h1>{{ t('welcome') }}</h1>
-    <button @click="setLocale('fr')">Français</button>
-  </div>
-</template>
-```
-
-### Svelte
-
-```typescript
-import { createI18n } from '@vielzeug/i18nit';
-import { writable } from 'svelte/store';
-
-const i18n = createI18n({ locale: 'en' });
-export const locale = writable(i18n.getLocale());
-
-i18n.subscribe((newLocale) => {
-  locale.set(newLocale);
-});
-
-export const t = i18n.t.bind(i18n);
-export const setLocale = i18n.setLocale.bind(i18n);
-
-// Usage
-<script>
-  import { t, setLocale } from './i18n';
-</script>
-
-<h1>{$t('welcome')}</h1>
-<button on:click={() => setLocale('fr')}>Français</button>
-```
-
-## Best Practices
-
-### 1. Organize Translations by Feature
-
-```typescript
-const messages = {
-  en: {
-    'auth.login.title': 'Login',
-    'auth.register.title': 'Register',
-    'dashboard.stats.users': 'Users',
-    'dashboard.stats.revenue': 'Revenue',
-  },
-};
-```
-
-### 2. Use Namespaces for Large Apps
-
-```typescript
-const authTranslations = i18n.namespace('auth');
-const dashboardTranslations = i18n.namespace('dashboard');
-```
-
-### 3. Lazy Load Translations
-
-```typescript
-const i18n = createI18n({
-  loaders: {
-    'en-US': () => import('./locales/en-US.json'),
-    'es-ES': () => import('./locales/es-ES.json'),
-  },
-});
-```
-
-### 4. Type-Safe Translation Keys
-
-```typescript
-type TranslationKeys = 'auth.login.title' | 'auth.register.title' | 'dashboard.welcome';
-
-function t(key: TranslationKeys, vars?: Record<string, unknown>) {
-  return i18n.t(key, vars);
-}
-```
-
-## TypeScript Support
-
-Full TypeScript support with type inference:
-
-```typescript
-import { createI18n, type Messages, type I18nConfig } from '@vielzeug/i18nit';
-
-// Define your messages type
-interface MyMessages extends Messages {
-  greeting: string;
-  items: {
-    zero: string;
-    one: string;
-    other: string;
-  };
-}
-
-const config: I18nConfig = {
-  locale: 'en',
-  messages: {
-    en: {
-      greeting: 'Hello!',
-      items: { zero: 'No items', one: 'One item', other: '{count} items' },
-    } satisfies MyMessages,
-  },
-};
-
-const i18n = createI18n(config);
-```
-
-## 📖 Documentation
-
-- [**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
+## Features
 
-MIT © [Helmuth Saatkamp](https://github.com/helmuthdu)
+- Typed translation keys from your message tree
+- Dot-notation nested key lookup
+- ICU-style interpolation with object/array path support
+- Plural messages (`zero/one/two/few/many/other`) via `Intl.PluralRules`
+- Locale chain fallback (`sr-Latn-RS -> sr-Latn -> sr`) + configured fallback locales
+- Async locale loading (`ensureLocale`, `switchLocale`, `registerLoader`, `reload`)
+- Catalog updates (`add` deep-merge, `replace` full replace)
+- Subscription API with batched notifications (`batch`, `subscribe`)
+- Intl format helpers (`number`, `date`, `list`, `relative`, `currency`)
+- Namespace and locale-bound views (`scope`, `withLocale`)
+- Diagnostic hooks (`onDiagnostic`) and missing-key hook (`onMissing`)
 
-## 🤝 Contributing
+## API At a Glance
 
-Contributions are welcome! Check our [GitHub repository](https://github.com/helmuthdu/vielzeug).
+- `createI18n<T>(options?) => I18n<T>`
+- `type BoundI18n<T>`
+- `type I18n<T>`
+- `type I18nOptions<T>`
+- `type Messages`, `TranslationKey`, `TranslationKeyParam`, `PluralKeys`, `NamespaceKeys`
 
-## 🔗 Links
+## Documentation
 
-- [GitHub Repository](https://github.com/helmuthdu/vielzeug)
-- [Documentation](https://helmuthdu.github.io/vielzeug/deposit)
-- [NPM Package](https://www.npmjs.com/package/@vielzeug/deposit)
-- [Issue Tracker](https://github.com/helmuthdu/vielzeug/issues)
+- [Overview](https://vielzeug.dev/i18nit/)
+- [Usage Guide](https://vielzeug.dev/i18nit/usage)
+- [API Reference](https://vielzeug.dev/i18nit/api)
+- [Examples](https://vielzeug.dev/i18nit/examples)
 
----
+## License
 
-Part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) ecosystem – A collection of type-safe utilities for modern web development.
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.