feat: implement useLocalizer hook for translation management; update README and tests

Author: iqbalhasandev

README.md

@@ -1,12 +1,13 @@
 # @devwizard/laravel-localizer-react
 
-🌍 React integration for Laravel Localizer with Vite plugin, `useTranslation` hook, and automatic TypeScript generation.
+🌍 React integration for Laravel Localizer with Vite plugin, `useLocalizer` hook, and automatic TypeScript generation.
 
 ## Features
 
 - ✅ **Automatic Generation**: Vite plugin watches for language file changes and regenerates TypeScript files
 - ✅ **Type-Safe**: Full TypeScript support with auto-generated types
-- ✅ **React Hooks**: Intuitive `useTranslation` hook for React components
+- ✅ **React Hooks**: Intuitive `useLocalizer` hook for React components
+- ✅ **Customizable Path**: By default reads from `@/lang` folder, customizable via options
 - ✅ **Laravel-Compatible**: Matches Laravel's translation API (`__`, `trans`, `choice`)
 - ✅ **Inertia.js Integration**: Seamlessly works with Inertia.js page props
 - ✅ **RTL Support**: Built-in right-to-left language support
@@ -63,10 +64,10 @@ This creates TypeScript files in `resources/js/lang/` directory.
 ### Basic Usage
 
 ```tsx
-import { useTranslation } from '@devwizard/laravel-localizer-react';
+import { useLocalizer } from '@devwizard/laravel-localizer-react';
 
 function MyComponent() {
-  const { __ } = useTranslation();
+  const { __ } = useLocalizer();
 
   return (
     <div>
@@ -77,13 +78,42 @@ function MyComponent() {
 }
 ```
 
+### Custom Translations Path
+
+By default, translations are read from the `@/lang` folder (which maps to `resources/js/lang`). You can customize this path:
+
+```tsx
+import { useLocalizer } from '@devwizard/laravel-localizer-react';
+
+function MyComponent() {
+  // Use custom translations directory
+  const { __ } = useLocalizer({ langPath: '@/translations' });
+
+  return <h1>{__('welcome')}</h1>;
+}
+```
+
+**Note:** Ensure your Vite config has the corresponding path alias:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': '/resources/js',
+      '@/translations': '/resources/js/translations',
+    },
+  },
+});
+```
+
 ### With Replacements
 
 ```tsx
-import { useTranslation } from '@devwizard/laravel-localizer-react';
+import { useLocalizer } from '@devwizard/laravel-localizer-react';
 
 function Greeting() {
-  const { __ } = useTranslation();
+  const { __ } = useLocalizer();
 
   return (
     <div>
@@ -97,10 +127,10 @@ function Greeting() {
 ### Pluralization
 
 ```tsx
-import { useTranslation } from '@devwizard/laravel-localizer-react';
+import { useLocalizer } from '@devwizard/laravel-localizer-react';
 
 function ItemCount({ count }: { count: number }) {
-  const { choice } = useTranslation();
+  const { choice } = useLocalizer();
 
   return <p>{choice('items', count)}</p>;
 }
@@ -109,10 +139,10 @@ function ItemCount({ count }: { count: number }) {
 ### RTL Support
 
 ```tsx
-import { useTranslation } from '@devwizard/laravel-localizer-react';
+import { useLocalizer } from '@devwizard/laravel-localizer-react';
 
 function App() {
-  const { dir, locale } = useTranslation();
+  const { dir, locale } = useLocalizer();
 
   return (
     <div dir={dir} lang={locale}>
@@ -125,10 +155,10 @@ function App() {
 ### Check Translation Exists
 
 ```tsx
-import { useTranslation } from '@devwizard/laravel-localizer-react';
+import { useLocalizer } from '@devwizard/laravel-localizer-react';
 
 function ConditionalMessage() {
-  const { __, has } = useTranslation();
+  const { __, has } = useLocalizer();
 
   if (!has('special.message')) {
     return null;
@@ -140,9 +170,17 @@ function ConditionalMessage() {
 
 ## API Reference
 
-### `useTranslation()`
+### `useLocalizer(options?)`
+
+Main hook for accessing translations and locale information.
+
+**Options:**
+
+| Option     | Type     | Default    | Description                                  |
+| ---------- | -------- | ---------- | -------------------------------------------- |
+| `langPath` | `string` | `'@/lang'` | Custom path to translations directory        |
 
-Returns an object with the following properties and methods:
+**Returns:**
 
 | Property           | Type                                        | Description                         |
 | ------------------ | ------------------------------------------- | ----------------------------------- |

__tests__/useTranslation.test.tsx __tests__/useLocalizer.test.tsx__tests__/useTranslation.test.tsx renamed to __tests__/useLocalizer.test.tsx

@@ -1,11 +1,11 @@
-import { renderHook } from '@testing-library/react';
 import { usePage } from '@inertiajs/react';
-import { useTranslation } from '../hooks/useTranslation';
+import { renderHook } from '@testing-library/react';
+import { useLocalizer } from '../hooks/useLocalizer';
 
 // Mock usePage
 const mockUsePage = usePage as jest.MockedFunction<typeof usePage>;
 
-describe('useTranslation', () => {
+describe('useLocalizer', () => {
   beforeEach(() => {
     // Setup default mock
     mockUsePage.mockReturnValue({
@@ -48,68 +48,68 @@ describe('useTranslation', () => {
 
   describe('Basic Translation', () => {
     it('should return translated string for a valid key', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('welcome')).toBe('Welcome');
     });
 
     it('should return the key if translation is not found', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('missing.key')).toBe('missing.key');
     });
 
     it('should support nested keys with dot notation', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('validation.required')).toBe('This field is required');
     });
   });
 
   describe('Placeholder Replacement', () => {
     it('should replace placeholders with :placeholder format', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('greeting.hello', { name: 'John' })).toBe('Hello John!');
     });
 
     it('should replace multiple placeholders', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('items.count', { count: 5 })).toBe('You have 5 items');
     });
 
     it('should handle numeric replacements', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('items.count', { count: 0 })).toBe('You have 0 items');
     });
   });
 
   describe('Fallback', () => {
     it('should use fallback if translation key is missing', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('missing.key', {}, 'Default text')).toBe('Default text');
     });
 
     it('should not use fallback if translation exists', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('welcome', {}, 'Fallback')).toBe('Welcome');
     });
   });
 
   describe('Aliases', () => {
     it('trans should work as alias for __', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.trans('welcome')).toBe('Welcome');
       expect(result.current.trans('welcome')).toBe(result.current.__('welcome'));
     });
 
     it('lang should work as alias for __', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.lang('welcome')).toBe('Welcome');
       expect(result.current.lang('welcome')).toBe(result.current.__('welcome'));
@@ -118,22 +118,22 @@ describe('useTranslation', () => {
 
   describe('has() method', () => {
     it('should return true for existing keys', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.has('welcome')).toBe(true);
       expect(result.current.has('validation.required')).toBe(true);
     });
 
     it('should return false for missing keys', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.has('missing.key')).toBe(false);
     });
   });
 
   describe('choice() method', () => {
     it('should include count in replacements', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.choice('items.count', 5)).toBe('You have 5 items');
     });
@@ -142,21 +142,21 @@ describe('useTranslation', () => {
       (window as any).__LARAVEL_LOCALIZER_TRANSLATIONS__.en['user.items'] =
         ':name has :count items';
 
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.choice('user.items', 3, { name: 'Alice' })).toBe('Alice has 3 items');
     });
   });
 
   describe('Locale Information', () => {
     it('should return current locale', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.locale).toBe('en');
     });
 
     it('should return text direction', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.dir).toBe('ltr');
     });
@@ -177,13 +177,13 @@ describe('useTranslation', () => {
         version: null,
       });
 
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.dir).toBe('rtl');
     });
 
     it('should return available locales', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.availableLocales).toEqual({
         en: { label: 'English', flag: '🇺🇸', dir: 'ltr' },
@@ -194,7 +194,7 @@ describe('useTranslation', () => {
 
   describe('getLocales() method', () => {
     it('should return array of locale codes', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.getLocales()).toEqual(['en', 'bn']);
     });
@@ -214,15 +214,15 @@ describe('useTranslation', () => {
         version: null,
       });
 
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.getLocales()).toEqual([]);
     });
   });
 
   describe('Translations object', () => {
     it('should expose all translations', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.translations).toEqual({
         welcome: 'Welcome',
@@ -244,7 +244,7 @@ describe('useTranslation', () => {
         version: null,
       });
 
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.locale).toBe('en'); // Default
       expect(result.current.dir).toBe('ltr'); // Default
@@ -253,7 +253,7 @@ describe('useTranslation', () => {
     it('should handle missing translations gracefully', () => {
       const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
 
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       // Since translations exist in the test setup, verify basic functionality works
       expect(result.current.__('test.key')).toBe('test.key');
@@ -263,21 +263,21 @@ describe('useTranslation', () => {
     });
 
     it('should handle empty string replacements', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('greeting.hello', { name: '' })).toBe('Hello !');
     });
 
     it('should handle undefined replacements', () => {
-      const { result } = renderHook(() => useTranslation());
+      const { result } = renderHook(() => useLocalizer());
 
       expect(result.current.__('greeting.hello', undefined)).toBe('Hello :name!');
     });
   });
 
   describe('Reactivity', () => {
     it('should update when locale changes', () => {
-      const { result, rerender } = renderHook(() => useTranslation());
+      const { result, rerender } = renderHook(() => useLocalizer());
 
       expect(result.current.__('welcome')).toBe('Welcome');