i18n-typed-store 0.1.0 → 0.1.1

package/README.md

@@ -10,6 +10,10 @@ Type-safe translation store for managing i18n locales with full TypeScript suppo
 - ✅ **Pluralization support** - Built-in plural form selector using `Intl.PluralRules`
 - ✅ **Flexible module loading** - Support for any module format (ESM, CommonJS, dynamic imports)
 - ✅ **Zero runtime dependencies** - Lightweight and framework-agnostic
+- ✅ **React integration** - Hooks and components for React applications
+- ✅ **SSR/SSG support** - Built-in utilities for server-side rendering
+- ✅ **Fallback locales** - Automatic merging with fallback translations
+- ✅ **Caching** - Built-in translation caching for better performance
 
 ## Installation
 
@@ -55,24 +59,212 @@ type TranslationData = {
   };
 };
 
-// Create the store
-const storeFactory = createTranslationStore(
+// Create the store factory
+const storeFactory = createTranslationStore({
   translations,
   locales,
-  async (locale, translation) => {
+  loadModule: async (locale, translation) => {
     // Load translation module dynamically
     const module = await import(`./locales/${locale}/${translation}.json`);
-    return module.default;
+    return module;
   },
-  (module, locale, translation) => module // Extract translation data
-);
+  extractTranslation: (module, locale, translation) => {
+    // Extract translation data from module
+    return module.default || module;
+  },
+  defaultLocale: 'en',
+  useFallback: true,
+  fallbackLocale: 'en',
+});
 
 // Create typed store
 const store = storeFactory.type<TranslationData>();
 
 // Load and use translations
-await store.common.load('en');
-console.log(store.common.translation?.title); // Type-safe access
+await store.translations.common.load('en');
+const title = store.translations.common.currentTranslation?.title; // Type-safe access
+```
+
+### React Usage
+
+```tsx
+import { createTranslationStore } from 'i18n-typed-store';
+import { I18nTypedStoreProvider, useI18nTranslation, useI18nLocale } from 'i18n-typed-store/react';
+
+// Setup store (same as above)
+const storeFactory = createTranslationStore({
+  translations: { common: 'common' },
+  locales: { en: 'en', ru: 'ru' },
+  loadModule: async (locale, translation) => {
+    return await import(`./locales/${locale}/${translation}.json`);
+  },
+  extractTranslation: (module) => module.default,
+  defaultLocale: 'en',
+});
+
+type TranslationData = {
+  common: { greeting: string; title: string };
+};
+
+const store = storeFactory.type<TranslationData>();
+
+// In your App component
+function App() {
+  return (
+    <I18nTypedStoreProvider store={store}>
+      <MyComponent />
+    </I18nTypedStoreProvider>
+  );
+}
+
+// In your components
+function MyComponent() {
+  const translations = useI18nTranslation('common');
+  const { locale, setLocale } = useI18nLocale();
+
+  if (!translations) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div>
+      <h1>{translations.title}</h1>
+      <p>{translations.greeting}</p>
+      <button onClick={() => setLocale('ru')}>Switch to Russian</button>
+    </div>
+  );
+}
+```
+
+### React Suspense Support
+
+```tsx
+import { Suspense } from 'react';
+import { useI18nTranslationLazy } from 'i18n-typed-store/react';
+
+function MyComponent() {
+  // This hook throws a promise if translation is not loaded (for Suspense)
+  const translations = useI18nTranslationLazy('common');
+
+  return (
+    <div>
+      <h1>{translations.title}</h1>
+      <p>{translations.greeting}</p>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <I18nTypedStoreProvider store={store} suspenseMode="first-load-locale">
+      <Suspense fallback={<div>Loading translations...</div>}>
+        <MyComponent />
+      </Suspense>
+    </I18nTypedStoreProvider>
+  );
+}
+```
+
+### SSR with Next.js
+
+```typescript
+// lib/i18n.ts
+import { createTranslationStore } from 'i18n-typed-store';
+import { getLocaleFromRequest, initializeStore } from 'i18n-typed-store/react';
+
+const translations = { common: 'common', errors: 'errors' } as const;
+const locales = { en: 'en', ru: 'ru' } as const;
+
+export const storeFactory = createTranslationStore({
+  translations,
+  locales,
+  loadModule: async (locale, translation) => {
+    return await import(`./locales/${locale}/${translation}.json`);
+  },
+  extractTranslation: (module) => module.default,
+  defaultLocale: 'en',
+});
+
+type TranslationData = {
+  common: { title: string };
+  errors: { notFound: string };
+};
+
+export type Store = ReturnType<typeof storeFactory.type<TranslationData>>;
+```
+
+```typescript
+// pages/_app.tsx or app/layout.tsx
+import { I18nTypedStoreProvider } from 'i18n-typed-store/react';
+import { storeFactory } from '../lib/i18n';
+
+const store = storeFactory.type<TranslationData>();
+
+function MyApp({ Component, pageProps }: AppProps) {
+  return (
+    <I18nTypedStoreProvider store={store}>
+      <Component {...pageProps} />
+    </I18nTypedStoreProvider>
+  );
+}
+```
+
+```typescript
+// pages/index.tsx (getServerSideProps)
+import type { GetServerSidePropsContext } from 'next';
+import { getLocaleFromRequest, initializeStore } from 'i18n-typed-store/react';
+import { storeFactory } from '../lib/i18n';
+
+export async function getServerSideProps(context: GetServerSidePropsContext) {
+  const locale = getLocaleFromRequest(context, {
+    defaultLocale: 'en',
+    availableLocales: ['en', 'ru'],
+    cookieName: 'locale',
+    queryParamName: 'locale',
+  });
+
+  const store = storeFactory.type<TranslationData>();
+  initializeStore(store, locale);
+
+  // Preload translations if needed
+  await store.translations.common.load(locale);
+
+  return {
+    props: {
+      locale,
+      // You can pass translations as props or use context
+    },
+  };
+}
+```
+
+```typescript
+// app/page.tsx (App Router)
+import { getLocaleFromRequest, initializeStore } from 'i18n-typed-store/react';
+import { storeFactory } from '../lib/i18n';
+import { headers, cookies } from 'next/headers';
+
+export default async function Page() {
+  const headersList = await headers();
+  const cookieStore = await cookies();
+  
+  const locale = getLocaleFromRequest(
+    {
+      headers: Object.fromEntries(headersList),
+      cookies: Object.fromEntries(cookieStore),
+    },
+    {
+      defaultLocale: 'en',
+      availableLocales: ['en', 'ru'],
+    }
+  );
+
+  const store = storeFactory.type<TranslationData>();
+  initializeStore(store, locale);
+  await store.translations.common.load(locale);
+
+  return <div>...</div>;
+}
 ```
 
 ## Core API
@@ -82,34 +274,51 @@ console.log(store.common.translation?.title); // Type-safe access
 Creates a type-safe translation store with lazy loading support.
 
 ```typescript
-const storeFactory = createTranslationStore<T, L, Module>(
-  translations: T,
-  locales: L,
-  loadModule: (locale: keyof L, translation: keyof T) => Promise<Module>,
-  extractTranslation: (module: Module, locale: keyof L, translation: keyof T) => unknown
-);
+function createTranslationStore<T, L, Module>(options: {
+  translations: T;
+  locales: L;
+  loadModule: (locale: keyof L, namespace: keyof T) => Promise<Module>;
+  extractTranslation: (module: Module, locale: keyof L, namespace: keyof T) => unknown | Promise<unknown>;
+  defaultLocale: keyof L;
+  useFallback?: boolean;
+  fallbackLocale?: keyof L;
+  deleteOtherLocalesAfterLoad?: boolean;
+  loadFromCache?: boolean;
+  changeLocaleEventName?: string;
+}): {
+  type<M extends { [K in keyof T]: any }>(): TranslationStore<T, L, M>;
+}
 ```
 
-**Parameters:**
+**Options:**
 
 - `translations` - Object with translation keys (e.g., `{ common: 'common', errors: 'errors' }`)
 - `locales` - Object with locale keys (e.g., `{ en: 'en', ru: 'ru' }`)
 - `loadModule` - Async function to load a translation module
-- `extractTranslation` - Function to extract translation data from the loaded module. Receives the module, locale, and translation key as parameters, allowing for locale-specific or translation-specific extraction logic.
+- `extractTranslation` - Function to extract translation data from the loaded module. Receives the module, locale, and namespace key as parameters
+- `defaultLocale` - Default locale key to use
+- `useFallback` - Whether to use fallback locale for missing translations (default: `false`)
+- `fallbackLocale` - Fallback locale key (default: `defaultLocale`)
+- `deleteOtherLocalesAfterLoad` - Whether to delete translations for other locales after loading (default: `false`)
+- `loadFromCache` - Whether to load translations from cache by default (default: `true`)
+- `changeLocaleEventName` - Event name for locale change events (default: `'change-locale'`)
 
 **Returns:** Object with `type<M>()` method that creates a typed store.
 
 **Example:**
 
 ```typescript
-const storeFactory = createTranslationStore(
-  { common: 'common' },
-  { en: 'en', ru: 'ru' },
-  async (locale, translation) => {
+const storeFactory = createTranslationStore({
+  translations: { common: 'common' },
+  locales: { en: 'en', ru: 'ru' },
+  loadModule: async (locale, translation) => {
     return await import(`./locales/${locale}/${translation}.json`);
   },
-  (module, locale, translation) => module.default
-);
+  extractTranslation: (module, locale, translation) => module.default,
+  defaultLocale: 'en',
+  useFallback: true,
+  fallbackLocale: 'en',
+});
 
 type TranslationData = {
   common: { title: string; description: string };
@@ -118,10 +327,10 @@ type TranslationData = {
 const store = storeFactory.type<TranslationData>();
 
 // Load translation
-await store.common.load('en');
+await store.translations.common.load('en');
 
 // Access translation (type-safe)
-const title = store.common.translation?.title;
+const title = store.translations.common.currentTranslation?.title;
 ```
 
 ### `createTranslationModuleMap`
@@ -129,11 +338,11 @@ const title = store.common.translation?.title;
 Creates a map of translation module loaders for all combinations of translations and locales.
 
 ```typescript
-const moduleMap = createTranslationModuleMap<T, L, Module>(
+function createTranslationModuleMap<T, L, Module>(
   translations: T,
   locales: L,
   loadModule: (locale: keyof L, translation: keyof T) => Promise<Module>
-);
+): Record<keyof T, Record<keyof L, () => Promise<Module>>>
 ```
 
 **Example:**
@@ -157,7 +366,10 @@ const module = await loader();
 Creates a plural form selector function for a specific locale using `Intl.PluralRules`.
 
 ```typescript
-const selectPlural = createPluralSelector(locale: string);
+function createPluralSelector(
+  locale: string,
+  options?: { strict?: boolean }
+): (count: number, variants: PluralVariants) => string
 ```
 
 **Example:**
@@ -194,43 +406,147 @@ selectPlural(2, variants);  // => 'яблока'
 selectPlural(5, variants);  // => 'яблок'
 ```
 
+## React API
+
+### `I18nTypedStoreProvider`
+
+Provider component that wraps your application to provide translation store context.
+
+```tsx
+<I18nTypedStoreProvider 
+  store={store} 
+  suspenseMode="first-load-locale"
+>
+  {children}
+</I18nTypedStoreProvider>
+```
+
+**Props:**
+
+- `store` - Translation store instance
+- `suspenseMode` - Suspense mode: `'once'` | `'first-load-locale'` | `'change-locale'` (default: `'first-load-locale'`)
+- `children` - React children
+
+### `useI18nTranslation`
+
+Hook for accessing translations with automatic loading. Returns `undefined` if translation is not yet loaded.
+
+```tsx
+const translations = useI18nTranslation('common', fromCache?: boolean);
+```
+
+### `useI18nTranslationLazy`
+
+Hook for accessing translations with React Suspense support. Throws a promise if translation is not loaded.
+
+```tsx
+const translations = useI18nTranslationLazy('common', fromCache?: boolean);
+```
+
+### `useI18nLocale`
+
+Hook for accessing and managing the current locale.
+
+```tsx
+const { locale, setLocale } = useI18nLocale();
+```
+
+### `Safe`
+
+Component that safely extracts strings from translation objects, catching errors.
+
+```tsx
+<Safe
+  errorComponent={<span>N/A</span>}
+  errorHandler={(error) => console.error(error)}
+>
+  {() => translations.common.pages.main.title}
+</Safe>
+```
+
+## SSR API
+
+### `getLocaleFromRequest`
+
+Gets locale from SSR request context (query params, cookies, headers).
+
+```typescript
+function getLocaleFromRequest<L extends Record<string, string>>(
+  context: RequestContext,
+  options: {
+    defaultLocale: string;
+    availableLocales: readonly string[];
+    headerName?: string;
+    cookieName?: string;
+    queryParamName?: string;
+    parseAcceptLanguage?: boolean;
+  }
+): keyof L
+```
+
+**Example:**
+
+```typescript
+const locale = getLocaleFromRequest(context, {
+  defaultLocale: 'en',
+  availableLocales: ['en', 'ru'],
+  cookieName: 'locale',
+  queryParamName: 'locale',
+  headerName: 'accept-language',
+  parseAcceptLanguage: true,
+});
+```
+
+### `initializeStore`
+
+Initializes translation store with a specific locale for SSR.
+
+```typescript
+function initializeStore<T, L, M>(
+  store: TranslationStore<T, L, M>,
+  locale: keyof L
+): void
+```
+
 ## Advanced Usage
 
 ### Working with Dynamic Imports
 
 ```typescript
-const storeFactory = createTranslationStore(
+const storeFactory = createTranslationStore({
   translations,
   locales,
-  async (locale, translation) => {
+  loadModule: async (locale, translation) => {
     // Dynamic import with error handling
     try {
       const module = await import(
         `./locales/${locale}/${translation}.json`
       );
-      return module.default;
+      return module;
     } catch (error) {
       console.error(`Failed to load ${translation} for ${locale}`);
       throw error;
     }
   },
-  (module, locale, translation) => module
-);
+  extractTranslation: (module, locale, translation) => {
+    return module.default || module;
+  },
+  defaultLocale: 'en',
+});
 ```
 
 ### Custom Module Extraction
 
-The `extractTranslation` function receives the module, locale, and translation key, allowing for advanced extraction logic:
+The `extractTranslation` function receives the module, locale, and namespace key, allowing for advanced extraction logic:
 
 ```typescript
-const storeFactory = createTranslationStore(
+const storeFactory = createTranslationStore({
   translations,
   locales,
-  async (locale, translation) => {
-    // Load module that exports default
+  loadModule: async (locale, translation) => {
     return await import(`./locales/${locale}/${translation}.ts`);
   },
-  (module, locale, translation) => {
+  extractTranslation: (module, locale, translation) => {
     // Extract from module.default or module
     // You can use locale and translation parameters for custom logic
     if (locale === 'en' && translation === 'common') {
@@ -238,8 +554,9 @@ const storeFactory = createTranslationStore(
       return module.default?.en || module.default;
     }
     return module.default || module;
-  }
-);
+  },
+  defaultLocale: 'en',
+});
 ```
 
 ### Handling Multiple Translation Namespaces
@@ -262,12 +579,34 @@ type TranslationData = {
 const store = storeFactory.type<TranslationData>();
 
 // Load specific translations
-await store.common.load('en');
-await store.ui.load('en');
+await store.translations.common.load('en');
+await store.translations.ui.load('en');
 
 // Access translations
-const title = store.common.translation?.title;
-const saveButton = store.ui.translation?.buttons.save;
+const title = store.translations.common.currentTranslation?.title;
+const saveButton = store.translations.ui.currentTranslation?.buttons.save;
+```
+
+### Using Fallback Locales
+
+When `useFallback` is enabled, missing translations are automatically filled from the fallback locale:
+
+```typescript
+const storeFactory = createTranslationStore({
+  translations: { common: 'common' },
+  locales: { en: 'en', ru: 'ru' },
+  loadModule: async (locale, translation) => {
+    return await import(`./locales/${locale}/${translation}.json`);
+  },
+  extractTranslation: (module) => module.default,
+  defaultLocale: 'en',
+  useFallback: true,
+  fallbackLocale: 'en',
+});
+
+// If 'ru' translation is missing some keys, they will be filled from 'en'
+await store.translations.common.load('ru');
+// Result: merged translation with 'en' as fallback
 ```
 
 ## Type Safety
@@ -276,16 +615,16 @@ The library provides complete type safety:
 
 ```typescript
 // ✅ TypeScript knows all available translation keys
-const title = store.common.translation?.title;
+const title = store.translations.common.currentTranslation?.title;
 
 // ❌ TypeScript error: 'invalidKey' doesn't exist
-const invalid = store.common.translation?.invalidKey;
+const invalid = store.translations.common.currentTranslation?.invalidKey;
 
 // ✅ TypeScript knows all available locales
-await store.common.load('en');
+await store.translations.common.load('en');
 
 // ❌ TypeScript error: 'fr' is not a valid locale
-await store.common.load('fr');
+await store.translations.common.load('fr');
 ```
 
 ## Pluralization
@@ -307,61 +646,6 @@ The library uses `Intl.PluralRules` for plural form selection, supporting all Un
 - Arabic (zero/one/two/few/many/other)
 - And many more...
 
-## API Reference
-
-### `createTranslationStore`
-
-```typescript
-function createTranslationStore<
-  T extends Record<string, string>,
-  L extends Record<string, string>,
-  Module = unknown
->(
-  translations: T,
-  locales: L,
-  loadModule: (locale: keyof L, translation: keyof T) => Promise<Module>,
-  extractTranslation: (module: Module, locale: keyof L, translation: keyof T) => unknown
-): {
-  type<M extends { [K in keyof T]: Record<string, unknown> }>(): TranslationStore<T, L, M>;
-}
-```
-
-### `createTranslationModuleMap`
-
-```typescript
-function createTranslationModuleMap<
-  T extends Record<string, string>,
-  L extends Record<string, string>,
-  Module = unknown
->(
-  translations: T,
-  locales: L,
-  loadModule: (locale: keyof L, translation: keyof T) => Promise<Module>
-): Record<keyof T, Record<keyof L, () => Promise<Module>>>
-```
-
-### `createPluralSelector`
-
-```typescript
-function createPluralSelector(locale: string): (
-  count: number,
-  variants: PluralVariants
-) => string
-```
-
-### `PluralVariants`
-
-```typescript
-type PluralVariants = {
-  zero?: string;
-  one?: string;
-  two?: string;
-  few?: string;
-  many?: string;
-  other?: string;
-};
-```
-
 ## Examples
 
 ### Example: E-commerce Application
@@ -396,24 +680,25 @@ type TranslationData = {
   };
 };
 
-const storeFactory = createTranslationStore(
+const storeFactory = createTranslationStore({
   translations,
   locales,
-  async (locale, translation) => {
+  loadModule: async (locale, translation) => {
     return await import(`./locales/${locale}/${translation}.json`);
   },
-  (module, locale, translation) => module.default
-);
+  extractTranslation: (module) => module.default,
+  defaultLocale: 'en',
+});
 
 const store = storeFactory.type<TranslationData>();
 
 // Load translations
-await store.products.load('en');
-await store.cart.load('en');
+await store.translations.products.load('en');
+await store.translations.cart.load('en');
 
 // Use translations
-const productTitle = store.products.translation?.title;
-const cartTitle = store.cart.translation?.title;
+const productTitle = store.translations.products.currentTranslation?.title;
+const cartTitle = store.translations.cart.currentTranslation?.title;
 ```
 
 ### Example: Pluralization in Product List
@@ -435,6 +720,56 @@ getProductCountText(1);  // => "1 product"
 getProductCountText(5);  // => "5 products"
 ```
 
+## API Reference
+
+### `createTranslationStore`
+
+```typescript
+function createTranslationStore<
+  T extends Record<string, string>,
+  L extends Record<string, string>,
+  Module = unknown
+>(options: CreateTranslationStoreOptions<T, L, Module>): {
+  type<M extends { [K in keyof T]: any }>(): TranslationStore<T, L, M>;
+}
+```
+
+### `createTranslationModuleMap`
+
+```typescript
+function createTranslationModuleMap<
+  T extends Record<string, string>,
+  L extends Record<string, string>,
+  Module = unknown
+>(
+  translations: T,
+  locales: L,
+  loadModule: (locale: keyof L, translation: keyof T) => Promise<Module>
+): Record<keyof T, Record<keyof L, () => Promise<Module>>>
+```
+
+### `createPluralSelector`
+
+```typescript
+function createPluralSelector(
+  locale: string,
+  options?: { strict?: boolean }
+): (count: number, variants: PluralVariants) => string
+```
+
+### `PluralVariants`
+
+```typescript
+type PluralVariants = {
+  zero?: string;
+  one?: string;
+  two?: string;
+  few?: string;
+  many?: string;
+  other?: string;
+};
+```
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.