i18n-typed-store 0.1.0 → 0.1.2

package/README.md

@@ -1,15 +1,21 @@
 # i18n-typed-store
 
-Type-safe translation store for managing i18n locales with full TypeScript support. A lightweight, zero-dependency library for handling internationalization with compile-time type safety.
+Type-safe translation store for managing i18n locales with full TypeScript support. A lightweight, zero-dependency library for handling internationalization with compile-time type safety. Designed to work with TypeScript classes for translations, providing full IDE support (go-to definition, autocomplete) and support for JSX elements and methods in translations.
 
 ## Features
 
 - ✅ **Full TypeScript support** - Complete type safety for translations and locales
+- ✅ **IDE integration** - Go-to definition, autocomplete, and refactoring support with translation classes
 - ✅ **Lazy loading** - Load translations only when needed
 - ✅ **Type-safe API** - Compile-time validation of translation keys and locales
+- ✅ **Translation classes/objects** - Use TypeScript classes or objects for translations with JSX support and methods
 - ✅ **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
 
@@ -25,6 +31,17 @@ yarn add i18n-typed-store
 pnpm add i18n-typed-store
 ```
 
+## Example Project
+
+For a complete working example, check out the [React example project](https://github.com/ialexanderlvov/i18n-typed-store-react-example):
+
+```bash
+git clone https://github.com/ialexanderlvov/i18n-typed-store-react-example
+cd i18n-typed-store-react-example
+yarn
+yarn dev
+```
+
 ## Quick Start
 
 ### Basic Usage
@@ -32,6 +49,10 @@ pnpm add i18n-typed-store
 ```typescript
 import { createTranslationStore } from 'i18n-typed-store';
 
+// Import translation types for type safety
+import type CommonTranslationsEn from './translations/common/en';
+import type ErrorsTranslationsEn from './translations/errors/en';
+
 // Define your translation keys
 const translations = {
   common: 'common',
@@ -44,35 +65,267 @@ const locales = {
   ru: 'ru',
 } as const;
 
-// Define your translation data structure
-type TranslationData = {
-  common: {
-    title: string;
-    description: string;
-  };
-  errors: {
-    notFound: string;
-  };
-};
+// Define your translation data structure using imported types
+interface TranslationData extends Record<keyof typeof translations, any> {
+  common: CommonTranslationsEn;
+  errors: ErrorsTranslationsEn;
+}
 
-// Create the store
-const storeFactory = createTranslationStore(
+// Create the store factory
+const storeFactory = createTranslationStore({
   translations,
   locales,
-  async (locale, translation) => {
-    // Load translation module dynamically
-    const module = await import(`./locales/${locale}/${translation}.json`);
-    return module.default;
+  loadModule: async (locale, translation) => {
+    // Load translation class dynamically
+    return await import(`./translations/${translation}/${locale}.ts`);
   },
-  (module, locale, translation) => module // Extract translation data
-);
+  extractTranslation: (module) => {
+    // Instantiate the translation class
+    return new module.default();
+  },
+  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 with IDE go-to support
+```
+
+### React Usage
+
+```typescript
+// constants.ts
+export const TRANSLATIONS = {
+  common: 'common',
+} as const;
+
+export const LOCALES = {
+  en: 'en',
+  ru: 'ru',
+} as const;
+```
+
+```typescript
+// store.ts
+import { createTranslationStore } from 'i18n-typed-store';
+import type CommonTranslationsEn from './translations/common/en';
+import { TRANSLATIONS, LOCALES } from './constants';
+
+export interface ITranslationStoreTypes extends Record<keyof typeof TRANSLATIONS, any> {
+  common: CommonTranslationsEn;
+}
+
+export const store = createTranslationStore({
+  translations: TRANSLATIONS,
+  locales: LOCALES,
+  loadModule: async (locale, translation) => {
+    return await import(`./translations/${translation}/${locale}.tsx`);
+  },
+  extractTranslation: (module) => new module.default(),
+  defaultLocale: 'en',
+}).type<ITranslationStoreTypes>();
+```
+
+```typescript
+// hooks/useTranslation.ts
+import { useI18nTranslation } from 'i18n-typed-store/react/useI18nTranslation';
+import type { TRANSLATIONS, LOCALES } from '../constants';
+import type { ITranslationStoreTypes } from '../store';
+
+export const useTranslation = <K extends keyof typeof TRANSLATIONS>(translation: K) => {
+  return useI18nTranslation<typeof TRANSLATIONS, typeof LOCALES, ITranslationStoreTypes, K>(translation);
+};
+```
+
+```tsx
+// App.tsx
+import { I18nTypedStoreProvider, useI18nLocale } from 'i18n-typed-store/react';
+import { store } from './store';
+import { useTranslation } from './hooks/useTranslation';
+
+function App() {
+  return (
+    <I18nTypedStoreProvider store={store}>
+      <MyComponent />
+    </I18nTypedStoreProvider>
+  );
+}
+```
+
+```tsx
+// MyComponent.tsx
+function MyComponent() {
+  const translations = useTranslation('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
+
+```typescript
+// hooks/useTranslationLazy.ts
+import { useI18nTranslationLazy } from 'i18n-typed-store/react/useI18nTranslationLazy';
+import type { TRANSLATIONS, LOCALES } from '../constants';
+import type { ITranslationStoreTypes } from '../store';
+
+export const useTranslationLazy = <K extends keyof typeof TRANSLATIONS>(translation: K) => {
+  return useI18nTranslationLazy<typeof TRANSLATIONS, typeof LOCALES, ITranslationStoreTypes, K>(translation);
+};
+```
+
+```tsx
+// MyComponent.tsx
+import { useTranslationLazy } from './hooks/useTranslationLazy';
+
+function MyComponent() {
+  // This hook throws a promise if translation is not loaded (for Suspense)
+  const translations = useTranslationLazy('common');
+
+  return (
+    <div>
+      <h1>{translations.title}</h1>
+      <p>{translations.greeting}</p>
+    </div>
+  );
+}
+```
+
+```tsx
+// App.tsx
+import { Suspense } from 'react';
+import { I18nTypedStoreProvider } from 'i18n-typed-store/react';
+import { store } from './store';
+import { MyComponent } from './MyComponent';
+
+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 type CommonTranslationsEn from './translations/common/en';
+import type ErrorsTranslationsEn from './translations/errors/en';
+
+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(`./translations/${translation}/${locale}.tsx`);
+  },
+  extractTranslation: (module) => new module.default(),
+  defaultLocale: 'en',
+});
+
+interface TranslationData extends Record<keyof typeof translations, any> {
+  common: CommonTranslationsEn;
+  errors: ErrorsTranslationsEn;
+}
+
+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,46 +335,65 @@ 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) => {
-    return await import(`./locales/${locale}/${translation}.json`);
-  },
-  (module, locale, translation) => module.default
-);
+import type CommonTranslationsEn from './translations/common/en';
 
-type TranslationData = {
-  common: { title: string; description: string };
-};
+const storeFactory = createTranslationStore({
+  translations: { common: 'common' },
+  locales: { en: 'en', ru: 'ru' },
+  loadModule: async (locale, translation) => {
+    return await import(`./translations/${translation}/${locale}.tsx`);
+  },
+  extractTranslation: (module) => new module.default(),
+  defaultLocale: 'en',
+  useFallback: true,
+  fallbackLocale: 'en',
+});
+
+interface TranslationData extends Record<keyof typeof translations, any> {
+  common: CommonTranslationsEn;
+}
 
 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;
+// Access translation (type-safe with IDE go-to support)
+const title = store.translations.common.currentTranslation?.title;
 ```
 
 ### `createTranslationModuleMap`
@@ -129,11 +401,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:**
@@ -143,7 +415,7 @@ const moduleMap = createTranslationModuleMap(
   { common: 'common' },
   { en: 'en', ru: 'ru' },
   async (locale, translation) => {
-    return await import(`./locales/${locale}/${translation}.json`);
+    return await import(`./translations/${translation}/${locale}.tsx`);
   }
 );
 
@@ -157,7 +429,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,57 +469,360 @@ 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
+// Direct usage
+const translations = useI18nTranslation('common', fromCache?: boolean);
+
+// Typed wrapper (recommended)
+import { useI18nTranslation } from 'i18n-typed-store/react/useI18nTranslation';
+import type { TRANSLATIONS, LOCALES } from './constants';
+import type { ITranslationStoreTypes } from './store';
+
+export const useTranslation = <K extends keyof typeof TRANSLATIONS>(translation: K) => {
+  return useI18nTranslation<typeof TRANSLATIONS, typeof LOCALES, ITranslationStoreTypes, K>(translation);
+};
+
+// Usage
+const translations = useTranslation('common');
+```
+
+### `useI18nTranslationLazy`
+
+Hook for accessing translations with React Suspense support. Throws a promise if translation is not loaded.
+
+```tsx
+// Direct usage
+const translations = useI18nTranslationLazy('common', fromCache?: boolean);
+
+// Typed wrapper (recommended)
+import { useI18nTranslationLazy } from 'i18n-typed-store/react/useI18nTranslationLazy';
+import type { TRANSLATIONS, LOCALES } from './constants';
+import type { ITranslationStoreTypes } from './store';
+
+export const useTranslationLazy = <K extends keyof typeof TRANSLATIONS>(translation: K) => {
+  return useI18nTranslationLazy<typeof TRANSLATIONS, typeof LOCALES, ITranslationStoreTypes, K>(translation);
+};
+
+// Usage
+const translations = useTranslationLazy('common');
+```
+
+### `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
 
+### Translation Classes Structure
+
+The library is designed to work with TypeScript classes for translations, providing full type safety and IDE support (go-to definition, autocomplete). Here's an example of a translation class:
+
+```typescript
+// translations/common/en.tsx
+import { createPluralSelector } from 'i18n-typed-store';
+
+const plur = createPluralSelector('en');
+
+export default class CommonTranslationsEn {
+  title = 'Welcome';
+  loading = 'Loading...';
+  error = 'An error occurred';
+  
+  greeting = (
+    <>
+      Hello, <strong>World</strong>!
+    </>
+  );
+  
+  buttons = {
+    save: 'Save',
+    cancel: 'Cancel',
+    delete: 'Delete',
+  };
+  
+  messages = {
+    notFound: 'Not found',
+    unauthorized: (
+      <>
+        You are <strong>not authorized</strong> to perform this action
+      </>
+    ),
+  };
+
+  // Pluralization method
+  items = (count: number) =>
+    count + ' ' + plur(count, {
+      one: 'item',
+      other: 'items',
+    });
+}
+```
+
+```typescript
+// lib/i18n.ts
+import { createTranslationStore } from 'i18n-typed-store';
+import type CommonTranslationsEn from './translations/common/en';
+import type MainTranslationsEn from './translations/main/en';
+import type NewsTranslationsEn from './translations/news/en';
+import type SettingsTranslationsEn from './translations/settings/en';
+
+const translations = {
+  common: 'common',
+  main: 'main',
+  news: 'news',
+  settings: 'settings',
+} as const;
+
+const locales = {
+  en: 'en',
+  ru: 'ru',
+} as const;
+
+export interface ITranslationStoreTypes extends Record<keyof typeof translations, any> {
+  common: CommonTranslationsEn;
+  main: MainTranslationsEn;
+  news: NewsTranslationsEn;
+  settings: SettingsTranslationsEn;
+}
+
+export const store = createTranslationStore({
+  translations,
+  locales,
+  loadModule: (locale, namespace) => {
+    return import(`./translations/${namespace}/${locale}.tsx`);
+  },
+  extractTranslation: (module) => new module.default(),
+  defaultLocale: 'en',
+  deleteOtherLocalesAfterLoad: false,
+  loadFromCache: false,
+}).type<ITranslationStoreTypes>();
+```
+
+**Benefits of using classes:**
+
+- ✅ Full TypeScript type safety with IDE go-to definition support
+- ✅ Support for JSX elements in translations
+- ✅ Methods for pluralization and dynamic translations
+- ✅ Better code organization and maintainability
+- ✅ Compile-time validation of translation keys
+
+### Creating Typed Hook Wrappers
+
+For better type safety and IDE support, it's recommended to create typed wrapper hooks. This ensures full type inference and autocomplete when using translations in your components.
+
+```typescript
+// hooks/useTranslation.ts
+import { useI18nTranslation } from 'i18n-typed-store/react/useI18nTranslation';
+import type { TRANSLATIONS, LOCALES } from '../constants';
+import type { ITranslationStoreTypes } from '../store';
+
+export const useTranslation = <K extends keyof typeof TRANSLATIONS>(translation: K) => {
+  return useI18nTranslation<typeof TRANSLATIONS, typeof LOCALES, ITranslationStoreTypes, K>(translation);
+};
+```
+
+```typescript
+// hooks/useTranslationLazy.ts
+import { useI18nTranslationLazy } from 'i18n-typed-store/react/useI18nTranslationLazy';
+import type { TRANSLATIONS, LOCALES } from '../constants';
+import type { ITranslationStoreTypes } from '../store';
+
+export const useTranslationLazy = <K extends keyof typeof TRANSLATIONS>(translation: K) => {
+  return useI18nTranslationLazy<typeof TRANSLATIONS, typeof LOCALES, ITranslationStoreTypes, K>(translation);
+};
+```
+
+```typescript
+// constants.ts
+export const TRANSLATIONS = {
+  common: 'common',
+  main: 'main',
+  news: 'news',
+  settings: 'settings',
+} as const;
+
+export const LOCALES = {
+  en: 'en',
+  ru: 'ru',
+} as const;
+```
+
+**Usage in components:**
+
+```tsx
+import { useTranslation } from './hooks/useTranslation';
+import { useTranslationLazy } from './hooks/useTranslationLazy';
+
+// With useTranslation (returns undefined if not loaded)
+function MyComponent() {
+  const translations = useTranslation('common');
+  
+  if (!translations) {
+    return <div>Loading...</div>;
+  }
+  
+  return <div>{translations.title}</div>;
+}
+
+// With useTranslationLazy (for Suspense)
+function MyComponentLazy() {
+  const translations = useTranslationLazy('common');
+  
+  return <div>{translations.title}</div>;
+}
+```
+
+**Benefits:**
+
+- ✅ Full type safety with autocomplete
+- ✅ IDE go-to definition support
+- ✅ Compile-time validation of translation keys
+- ✅ Consistent API across your application
+
 ### 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`
+        `./translations/${translation}/${locale}.tsx`
       );
-      return module.default;
+      return module;
     } catch (error) {
       console.error(`Failed to load ${translation} for ${locale}`);
       throw error;
     }
   },
-  (module, locale, translation) => module
-);
+  extractTranslation: (module) => {
+    // Instantiate the translation class
+    return new module.default();
+  },
+  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
-    return await import(`./locales/${locale}/${translation}.ts`);
+  loadModule: async (locale, translation) => {
+    // Special handling for certain namespaces
+    if (translation === 'lang') {
+      return await import(`./translations/${translation}/index.tsx`);
+    }
+    return await import(`./translations/${translation}/${locale}.tsx`);
   },
-  (module, locale, translation) => {
-    // Extract from module.default or module
+  extractTranslation: (module) => {
+    // Instantiate the translation class
     // You can use locale and translation parameters for custom logic
-    if (locale === 'en' && translation === 'common') {
-      // Special handling for English common translations
-      return module.default?.en || module.default;
-    }
-    return module.default || module;
-  }
-);
+    return new module.default();
+  },
+  defaultLocale: 'en',
+});
 ```
 
 ### Handling Multiple Translation Namespaces
 
 ```typescript
+import type CommonTranslationsEn from './translations/common/en';
+import type ErrorsTranslationsEn from './translations/errors/en';
+import type UiTranslationsEn from './translations/ui/en';
+import type AdminTranslationsEn from './translations/admin/en';
+
 const translations = {
   common: 'common',
   errors: 'errors',
@@ -252,22 +830,44 @@ const translations = {
   admin: 'admin',
 } as const;
 
-type TranslationData = {
-  common: { title: string };
-  errors: { notFound: string };
-  ui: { buttons: { save: string } };
-  admin: { dashboard: { title: string } };
-};
+interface TranslationData extends Record<keyof typeof translations, any> {
+  common: CommonTranslationsEn;
+  errors: ErrorsTranslationsEn;
+  ui: UiTranslationsEn;
+  admin: AdminTranslationsEn;
+}
 
 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;
+// Access translations (with full IDE support)
+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(`./translations/${translation}/${locale}.tsx`);
+  },
+  extractTranslation: (module) => new 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 +876,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,6 +907,100 @@ The library uses `Intl.PluralRules` for plural form selection, supporting all Un
 - Arabic (zero/one/two/few/many/other)
 - And many more...
 
+## Examples
+
+### Complete Example Project
+
+For a full-featured example with React, TypeScript, and all features demonstrated, see the [example repository](https://github.com/ialexanderlvov/i18n-typed-store-react-example).
+
+### Example: E-commerce Application
+
+```typescript
+import type ProductsTranslationsEn from './translations/products/en';
+import type CartTranslationsEn from './translations/cart/en';
+import type CheckoutTranslationsEn from './translations/checkout/en';
+
+const translations = {
+  products: 'products',
+  cart: 'cart',
+  checkout: 'checkout',
+} as const;
+
+const locales = {
+  en: 'en',
+  ru: 'ru',
+  de: 'de',
+} as const;
+
+interface TranslationData extends Record<keyof typeof translations, any> {
+  products: ProductsTranslationsEn;
+  cart: CartTranslationsEn;
+  checkout: CheckoutTranslationsEn;
+}
+
+const storeFactory = createTranslationStore({
+  translations,
+  locales,
+  loadModule: async (locale, translation) => {
+    return await import(`./translations/${translation}/${locale}.ts`);
+  },
+  extractTranslation: (module) => new module.default(),
+  defaultLocale: 'en',
+});
+
+const store = storeFactory.type<TranslationData>();
+
+// Load translations
+await store.translations.products.load('en');
+await store.translations.cart.load('en');
+
+// Use translations (with full IDE go-to support)
+const productTitle = store.translations.products.currentTranslation?.title;
+const cartTitle = store.translations.cart.currentTranslation?.title;
+```
+
+### Example: Pluralization in Product List
+
+```typescript
+// translations/products/en.tsx
+import { createPluralSelector } from 'i18n-typed-store';
+
+const plur = createPluralSelector('en');
+
+export default class ProductsTranslationsEn {
+  title = 'Products';
+  addToCart = 'Add to Cart';
+  price = 'Price';
+  
+  // Pluralization method
+  productCount = (count: number) =>
+    count + ' ' + plur(count, {
+      one: 'product',
+      other: 'products',
+    });
+  
+  itemsInCart = (count: number) =>
+    count + ' ' + plur(count, {
+      zero: 'No items',
+      one: 'item',
+      other: 'items',
+    }) + ' in cart';
+}
+
+// Usage in component with typed hook
+import { useTranslation } from './hooks/useTranslation';
+
+const translations = useTranslation('products');
+
+if (translations) {
+  translations.productCount(1);  // => "1 product"
+  translations.productCount(5);  // => "5 products"
+  translations.itemsInCart(0);  // => "0 No items in cart"
+  translations.itemsInCart(1);  // => "1 item in cart"
+  translations.itemsInCart(5);  // => "5 items in cart"
+}
+```
+
 ## API Reference
 
 ### `createTranslationStore`
@@ -316,13 +1010,8 @@ 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>;
+>(options: CreateTranslationStoreOptions<T, L, Module>): {
+  type<M extends { [K in keyof T]: any }>(): TranslationStore<T, L, M>;
 }
 ```
 
@@ -343,10 +1032,10 @@ function createTranslationModuleMap<
 ### `createPluralSelector`
 
 ```typescript
-function createPluralSelector(locale: string): (
-  count: number,
-  variants: PluralVariants
-) => string
+function createPluralSelector(
+  locale: string,
+  options?: { strict?: boolean }
+): (count: number, variants: PluralVariants) => string
 ```
 
 ### `PluralVariants`
@@ -362,79 +1051,6 @@ type PluralVariants = {
 };
 ```
 
-## Examples
-
-### Example: E-commerce Application
-
-```typescript
-const translations = {
-  products: 'products',
-  cart: 'cart',
-  checkout: 'checkout',
-} as const;
-
-const locales = {
-  en: 'en',
-  ru: 'ru',
-  de: 'de',
-} as const;
-
-type TranslationData = {
-  products: {
-    title: string;
-    addToCart: string;
-    price: string;
-  };
-  cart: {
-    title: string;
-    empty: string;
-    total: string;
-  };
-  checkout: {
-    title: string;
-    placeOrder: string;
-  };
-};
-
-const storeFactory = createTranslationStore(
-  translations,
-  locales,
-  async (locale, translation) => {
-    return await import(`./locales/${locale}/${translation}.json`);
-  },
-  (module, locale, translation) => module.default
-);
-
-const store = storeFactory.type<TranslationData>();
-
-// Load translations
-await store.products.load('en');
-await store.cart.load('en');
-
-// Use translations
-const productTitle = store.products.translation?.title;
-const cartTitle = store.cart.translation?.title;
-```
-
-### Example: Pluralization in Product List
-
-```typescript
-import { createPluralSelector } from 'i18n-typed-store';
-
-const selectPlural = createPluralSelector('en');
-
-function getProductCountText(count: number): string {
-  return selectPlural(count, {
-    one: `${count} product`,
-    other: `${count} products`,
-  });
-}
-
-// Usage
-getProductCountText(1);  // => "1 product"
-getProductCountText(5);  // => "5 products"
-```
-
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
@@ -450,3 +1066,7 @@ Alexander Lvov
 ## Repository
 
 [GitHub](https://github.com/ialexanderlvov/i18n-typed-store)
+
+## Example Project Git
+
+[React Example](https://github.com/ialexanderlvov/i18n-typed-store-react-example) - Complete working example with React, TypeScript, and all features demonstrated.