docs: update README with installation steps and usage instructions; enhance test setup for translations

feat: update useLocalizer to load translations from window.localizer for immediate access; bump version to 0.0.5

Author: iqbalhasandev

README.md

@@ -27,12 +27,41 @@ yarn add @devwizard/laravel-localizer-react
 
 ```bash
 composer require devwizardhq/laravel-localizer
-php artisan localizer:install --framework=react
+php artisan localizer:install
 ```
 
+The install command will:
+- ✅ Publish configuration files
+- ✅ Create default locale files
+- ✅ Install npm package (optional)
+- ✅ Generate initial TypeScript files
+
+**Note:** You'll need to manually add the bootstrap setup (see step 1 below).
+
 ## Setup
 
-### 1. Add Vite Plugin
+### 1. Initialize Translations in Bootstrap
+
+Add this to your `resources/js/bootstrap.ts`:
+
+```typescript
+import { translations } from '@/lang';
+
+declare global {
+    interface Window {
+        localizer: {
+            translations: Record<string, Record<string, string>>;
+        };
+    }
+}
+
+// Auto-initialize Laravel Localizer translations
+window.localizer = {
+    translations: translations,
+};
+```
+
+### 2. Add Vite Plugin
 
 Update your `vite.config.ts`:
 
@@ -51,14 +80,76 @@ export default defineConfig({
 });
 ```
 
-### 2. Generate Translation Files
+### 2. Add Vite Plugin
+
+Update your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { laravelLocalizer } from '@devwizard/laravel-localizer-react/vite';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    laravelLocalizer({
+      debug: true, // Enable debug logging (optional)
+    }),
+  ],
+});
+```
+
+### 3. Generate Translation Files
 
 ```bash
 php artisan localizer:generate --all
 ```
 
 This creates TypeScript files in `resources/js/lang/` directory.
 
+## How It Works
+
+The Laravel Localizer uses a simple and efficient approach:
+
+1. **Generate** - PHP generates TypeScript files from Laravel language files
+2. **Load** - Translations are loaded once at app startup via `window.localizer`
+3. **Access** - React components access translations synchronously via `useLocalizer` hook
+
+```
+┌─────────────────┐
+│  Laravel Lang   │  lang/en.json, lang/en/*.php
+│     Files       │
+└────────┬────────┘
+         │
+         │ php artisan localizer:generate
+         ▼
+┌─────────────────┐
+│   TypeScript    │  resources/js/lang/en.ts
+│     Files       │  resources/js/lang/index.ts
+└────────┬────────┘
+         │
+         │ import { translations } from '@/lang'
+         ▼
+┌─────────────────┐
+│ window.localizer│  { translations: { en: {...}, bn: {...} } }
+│                 │
+└────────┬────────┘
+         │
+         │ useLocalizer() hook
+         ▼
+┌─────────────────┐
+│ React Components│  {__('welcome')}
+└─────────────────┘
+```
+
+### Why `window.localizer`?
+
+- ✅ **Synchronous Access** - No async loading delays
+- ✅ **All Locales Ready** - All translations available immediately
+- ✅ **Build-time Optimization** - Vite can tree-shake unused translations
+- ✅ **Test-friendly** - Works in Jest/Vitest without mocking
+- ✅ **No Re-renders** - No useEffect or async state updates
+
 ## Usage
 
 ### Basic Usage

__tests__/setup.ts

@@ -5,6 +5,29 @@ jest.mock('@inertiajs/react', () => ({
   usePage: jest.fn(),
 }));
 
+// Setup window.localizer for tests
+beforeAll(() => {
+  (window as any).localizer = {
+    translations: {
+      en: {
+        welcome: 'Welcome',
+        'validation.required': 'This field is required',
+        'greeting.hello': 'Hello :name!',
+        'items.count': 'You have :count items',
+        'user.items': ':name has :count items',
+      },
+      ar: {
+        welcome: 'مرحبا',
+        'validation.required': 'هذا الحقل مطلوب',
+      },
+      bn: {
+        welcome: 'স্বাগতম',
+        'validation.required': 'এই ক্ষেত্রটি প্রয়োজনীয়',
+      },
+    },
+  };
+});
+
 // Suppress console errors during tests unless explicitly needed
 const originalError = console.error;
 beforeAll(() => {

__tests__/useLocalizer.test.tsx

@@ -229,6 +229,7 @@ describe('useLocalizer', () => {
         'validation.required': 'This field is required',
         'greeting.hello': 'Hello :name!',
         'items.count': 'You have :count items',
+        'user.items': ':name has :count items',
       });
     });
   });

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@devwizard/laravel-localizer-react",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "description": "React integration for Laravel Localizer with Vite plugin, useLocalizer hook, and automatic TypeScript generation",
   "main": "dist/index.js",

package.json

@@ -190,32 +190,32 @@ export function useLocalizer(options: UseLocalizerOptions = {}): UseLocalizerRet
 
   const availableLocales = useMemo(() => props.locale?.available || {}, [props.locale?.available]);
 
-  // Dynamically import translations from generated files
-  // Note: By default, translations are loaded from '@/lang' folder (resources/js/lang)
-  // Users can customize this path by passing langPath option
-  // The actual translations object will be available at runtime
+  // Load translations from window object (initialized in bootstrap.ts)
+  // The langPath option is used by the vite plugin to know where to watch for changes
+  // and where the generated files should be located
   const translations = useMemo<Record<string, string>>(() => {
     try {
-      // This will be resolved at build time by Vite
-      // The generated files are created by php artisan localizer:generate
-      interface WindowWithTranslations extends Window {
-        __LARAVEL_LOCALIZER_TRANSLATIONS__?: Record<string, Record<string, string>>;
+      // Translations are automatically loaded in bootstrap.ts from the generated files
+      // This provides immediate, synchronous access to all translations
+      interface WindowWithLocalizer extends Window {
+        localizer?: {
+          translations: Record<string, Record<string, string>>;
+        };
       }
-      const translations =
-        (window as WindowWithTranslations).__LARAVEL_LOCALIZER_TRANSLATIONS__?.[locale] || {};
+      const localizer = (window as WindowWithLocalizer).localizer;
 
-      // Note: langPath is stored for future use if needed for dynamic imports
-      // Currently, translations are loaded globally via window object
-      if (Object.keys(translations).length === 0 && langPath !== '@/lang') {
+      if (!localizer?.translations) {
         console.warn(
-          `[Laravel Localizer] Custom langPath '${langPath}' specified but translations not found. Ensure your vite.config has proper path alias.`
+          `[Laravel Localizer] Translations not initialized. Make sure bootstrap.ts imports from '${langPath}'.`
         );
+        return {};
       }
 
-      return translations;
-    } catch {
+      return localizer.translations[locale] || {};
+    } catch (error) {
       console.warn(
-        `[Laravel Localizer] Could not load translations for locale: ${locale}. Default path is '${langPath}'.`
+        `[Laravel Localizer] Could not load translations for locale: ${locale}`,
+        error
       );
       return {};
     }