i18n-typed-store 0.1.1 → 0.1.3

package/README.md

@@ -1,12 +1,14 @@
 # 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
@@ -29,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
@@ -36,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',
@@ -48,29 +65,23 @@ 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 factory
 const storeFactory = createTranslationStore({
   translations,
   locales,
   loadModule: async (locale, translation) => {
-    // Load translation module dynamically
-    const module = await import(`./locales/${locale}/${translation}.json`);
-    return module;
+    // Load translation class dynamically
+    return await import(`./translations/${translation}/${locale}.ts`);
   },
-  extractTranslation: (module, locale, translation) => {
-    // Extract translation data from module
-    return module.default || module;
+  extractTranslation: (module) => {
+    // Instantiate the translation class
+    return new module.default();
   },
   defaultLocale: 'en',
   useFallback: true,
@@ -82,33 +93,61 @@ const store = storeFactory.type<TranslationData>();
 
 // Load and use translations
 await store.translations.common.load('en');
-const title = store.translations.common.currentTranslation?.title; // Type-safe access
+const title = store.translations.common.currentTranslation?.title; // Type-safe access with IDE go-to support
 ```
 
 ### React Usage
 
-```tsx
+```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 { I18nTypedStoreProvider, useI18nTranslation, useI18nLocale } from 'i18n-typed-store/react';
+import type CommonTranslationsEn from './translations/common/en';
+import { TRANSLATIONS, LOCALES } from './constants';
 
-// Setup store (same as above)
-const storeFactory = createTranslationStore({
-  translations: { common: 'common' },
-  locales: { en: 'en', ru: 'ru' },
+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(`./locales/${locale}/${translation}.json`);
+    return await import(`./translations/${translation}/${locale}.tsx`);
   },
-  extractTranslation: (module) => module.default,
+  extractTranslation: (module) => new module.default(),
   defaultLocale: 'en',
-});
+}).type<ITranslationStoreTypes>();
+```
 
-type TranslationData = {
-  common: { greeting: string; title: string };
+```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);
 };
+```
 
-const store = storeFactory.type<TranslationData>();
+```tsx
+// App.tsx
+import { I18nTypedStoreProvider, useI18nLocale } from 'i18n-typed-store/react';
+import { store } from './store';
+import { useTranslation } from './hooks/useTranslation';
 
-// In your App component
 function App() {
   return (
     <I18nTypedStoreProvider store={store}>
@@ -116,10 +155,12 @@ function App() {
     </I18nTypedStoreProvider>
   );
 }
+```
 
-// In your components
+```tsx
+// MyComponent.tsx
 function MyComponent() {
-  const translations = useI18nTranslation('common');
+  const translations = useTranslation('common');
   const { locale, setLocale } = useI18nLocale();
 
   if (!translations) {
@@ -138,13 +179,24 @@ function MyComponent() {
 
 ### 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
-import { Suspense } from 'react';
-import { useI18nTranslationLazy } from 'i18n-typed-store/react';
+// MyComponent.tsx
+import { useTranslationLazy } from './hooks/useTranslationLazy';
 
 function MyComponent() {
   // This hook throws a promise if translation is not loaded (for Suspense)
-  const translations = useI18nTranslationLazy('common');
+  const translations = useTranslationLazy('common');
 
   return (
     <div>
@@ -153,6 +205,14 @@ function MyComponent() {
     </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 (
@@ -170,7 +230,8 @@ function App() {
 ```typescript
 // lib/i18n.ts
 import { createTranslationStore } from 'i18n-typed-store';
-import { getLocaleFromRequest, initializeStore } from 'i18n-typed-store/react';
+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;
@@ -179,16 +240,16 @@ export const storeFactory = createTranslationStore({
   translations,
   locales,
   loadModule: async (locale, translation) => {
-    return await import(`./locales/${locale}/${translation}.json`);
+    return await import(`./translations/${translation}/${locale}.tsx`);
   },
-  extractTranslation: (module) => module.default,
+  extractTranslation: (module) => new module.default(),
   defaultLocale: 'en',
 });
 
-type TranslationData = {
-  common: { title: string };
-  errors: { notFound: string };
-};
+interface TranslationData extends Record<keyof typeof translations, any> {
+  common: CommonTranslationsEn;
+  errors: ErrorsTranslationsEn;
+}
 
 export type Store = ReturnType<typeof storeFactory.type<TranslationData>>;
 ```
@@ -308,28 +369,30 @@ function createTranslationStore<T, L, Module>(options: {
 **Example:**
 
 ```typescript
+import type CommonTranslationsEn from './translations/common/en';
+
 const storeFactory = createTranslationStore({
   translations: { common: 'common' },
   locales: { en: 'en', ru: 'ru' },
   loadModule: async (locale, translation) => {
-    return await import(`./locales/${locale}/${translation}.json`);
+    return await import(`./translations/${translation}/${locale}.tsx`);
   },
-  extractTranslation: (module, locale, translation) => module.default,
+  extractTranslation: (module) => new module.default(),
   defaultLocale: 'en',
   useFallback: true,
   fallbackLocale: 'en',
 });
 
-type TranslationData = {
-  common: { title: string; description: string };
-};
+interface TranslationData extends Record<keyof typeof translations, any> {
+  common: CommonTranslationsEn;
+}
 
 const store = storeFactory.type<TranslationData>();
 
 // Load translation
 await store.translations.common.load('en');
 
-// Access translation (type-safe)
+// Access translation (type-safe with IDE go-to support)
 const title = store.translations.common.currentTranslation?.title;
 ```
 
@@ -352,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`);
   }
 );
 
@@ -432,7 +495,20 @@ Provider component that wraps your application to provide translation store cont
 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`
@@ -440,7 +516,20 @@ const translations = useI18nTranslation('common', fromCache?: boolean);
 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`
@@ -510,6 +599,172 @@ function initializeStore<T, L, M>(
 
 ## 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
@@ -520,7 +775,7 @@ const storeFactory = createTranslationStore({
     // Dynamic import with error handling
     try {
       const module = await import(
-        `./locales/${locale}/${translation}.json`
+        `./translations/${translation}/${locale}.tsx`
       );
       return module;
     } catch (error) {
@@ -528,8 +783,9 @@ const storeFactory = createTranslationStore({
       throw error;
     }
   },
-  extractTranslation: (module, locale, translation) => {
-    return module.default || module;
+  extractTranslation: (module) => {
+    // Instantiate the translation class
+    return new module.default();
   },
   defaultLocale: 'en',
 });
@@ -544,16 +800,16 @@ const storeFactory = createTranslationStore({
   translations,
   locales,
   loadModule: async (locale, translation) => {
-    return await import(`./locales/${locale}/${translation}.ts`);
+    // Special handling for certain namespaces
+    if (translation === 'lang') {
+      return await import(`./translations/${translation}/index.tsx`);
+    }
+    return await import(`./translations/${translation}/${locale}.tsx`);
   },
-  extractTranslation: (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',
 });
@@ -562,6 +818,11 @@ const storeFactory = createTranslationStore({
 ### 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',
@@ -569,12 +830,12 @@ 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>();
 
@@ -582,7 +843,7 @@ const store = storeFactory.type<TranslationData>();
 await store.translations.common.load('en');
 await store.translations.ui.load('en');
 
-// Access translations
+// Access translations (with full IDE support)
 const title = store.translations.common.currentTranslation?.title;
 const saveButton = store.translations.ui.currentTranslation?.buttons.save;
 ```
@@ -596,9 +857,9 @@ const storeFactory = createTranslationStore({
   translations: { common: 'common' },
   locales: { en: 'en', ru: 'ru' },
   loadModule: async (locale, translation) => {
-    return await import(`./locales/${locale}/${translation}.json`);
+    return await import(`./translations/${translation}/${locale}.tsx`);
   },
-  extractTranslation: (module) => module.default,
+  extractTranslation: (module) => new module.default(),
   defaultLocale: 'en',
   useFallback: true,
   fallbackLocale: 'en',
@@ -648,9 +909,17 @@ The library uses `Intl.PluralRules` for plural form selection, supporting all Un
 
 ## 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',
@@ -663,30 +932,19 @@ const locales = {
   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;
-  };
-};
+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(`./locales/${locale}/${translation}.json`);
+    return await import(`./translations/${translation}/${locale}.ts`);
   },
-  extractTranslation: (module) => module.default,
+  extractTranslation: (module) => new module.default(),
   defaultLocale: 'en',
 });
 
@@ -696,7 +954,7 @@ const store = storeFactory.type<TranslationData>();
 await store.translations.products.load('en');
 await store.translations.cart.load('en');
 
-// Use translations
+// Use translations (with full IDE go-to support)
 const productTitle = store.translations.products.currentTranslation?.title;
 const cartTitle = store.translations.cart.currentTranslation?.title;
 ```
@@ -704,20 +962,43 @@ const cartTitle = store.translations.cart.currentTranslation?.title;
 ### Example: Pluralization in Product List
 
 ```typescript
+// translations/products/en.tsx
 import { createPluralSelector } from 'i18n-typed-store';
 
-const selectPlural = createPluralSelector('en');
+const plur = createPluralSelector('en');
 
-function getProductCountText(count: number): string {
-  return selectPlural(count, {
-    one: `${count} product`,
-    other: `${count} products`,
-  });
+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
-getProductCountText(1);  // => "1 product"
-getProductCountText(5);  // => "5 products"
+// 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
@@ -785,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.

package/package.json

@@ -1,10 +1,22 @@
 {
 	"name": "i18n-typed-store",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "Type-safe translation store for managing i18n locales with full TypeScript support",
 	"main": "dist/index.js",
 	"module": "dist/index.mjs",
 	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.js"
+		},
+		"./react": {
+			"types": "./dist/react/index.d.ts",
+			"import": "./dist/react/index.mjs",
+			"require": "./dist/react/index.js"
+		}
+	},
 	"files": [
 		"dist"
 	],