@tooinfinity/lingua-react 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-01-14
+
+### Added
+
+- `useTranslations` hook for accessing Laravel Lingua translations in React components
+- `__()` translation function with support for dot notation keys (e.g., `messages.welcome`)
+- Parameter replacement support using Laravel's `:placeholder` syntax
+- `locale` - current locale accessor (defaults to `'en'`)
+- `locales` - available locales array accessor (defaults to `['en']`)
+- Full TypeScript support with exported `LinguaProps` and `TranslateFunction` types
+- Support for React 18+ and React 19+
+- Support for @inertiajs/react 1.0+ and 2.0+
+- ESM and CommonJS dual package distribution
+- Source maps for debugging

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TouwfiQ Meghlaoui <touwfiqdev@gmail.com> tooinfinity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @tooinfinity/lingua-react
+
+React bindings for [Laravel Lingua](https://github.com/tooinfinity/lingua) - seamless translations with Inertia.js.
+
+## Installation
+
+```bash
+npm install @tooinfinity/lingua-react
+```
+
+## Requirements
+
+- React 18+ or 19+
+- @inertiajs/react 1.0+ or 2.0+
+- Laravel Lingua (PHP package)
+
+## Usage
+
+### Basic Translation
+
+```tsx
+import { useTranslations } from '@tooinfinity/lingua-react';
+
+function Welcome() {
+  const { __, locale, locales } = useTranslations();
+
+  return (
+    <div>
+      <p>Current locale: {locale}</p>
+      <h1>{__('messages.welcome')}</h1>
+      <p>{__('messages.greeting', { name: 'John' })}</p>
+    </div>
+  );
+}
+```
+
+### Available Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `__` | `(key: string, replacements?: Record<string, string \| number>) => string` | Translation function (Laravel convention) |
+| `locale` | `string` | Current locale (default: `'en'`) |
+| `locales` | `string[]` | Available locales (default: `['en']`) |
+
+### Translation Keys
+
+Use dot notation for nested translations:
+
+```tsx
+// For translation file: { "messages": { "hello": "Hello :name" } }
+__('messages.hello', { name: 'World' }) // "Hello World"
+```
+
+### Locale Switcher Example
+
+```tsx
+import { useTranslations } from '@tooinfinity/lingua-react';
+import { router } from '@inertiajs/react';
+
+function LocaleSwitcher() {
+  const { locale, locales } = useTranslations();
+
+  const switchLocale = (newLocale: string) => {
+    router.post('/locale', { locale: newLocale });
+  };
+
+  return (
+    <select value={locale} onChange={(e) => switchLocale(e.target.value)}>
+      {locales.map((loc) => (
+        <option key={loc} value={loc}>
+          {loc.toUpperCase()}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type { LinguaProps, TranslateFunction } from '@tooinfinity/lingua-react';
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+```
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { useTranslations } from './useTranslations';
+export type { LinguaProps, TranslateFunction } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC"}

package/dist/lingua-react.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("@inertiajs/react");function u(){const{props:n}=i.usePage(),e=n.lingua;return{__:(o,s)=>{const c=o.split(".");let t=e==null?void 0:e.translations;for(const r of c){if(t==null)break;t=t[r]}return typeof t!="string"?o:s?Object.entries(s).reduce((r,[l,a])=>r.replace(new RegExp(`:${l}`,"g"),String(a)),t):t},locale:(e==null?void 0:e.locale)??"en",locales:(e==null?void 0:e.locales)??["en"]}}exports.useTranslations=u;
+//# sourceMappingURL=lingua-react.cjs.map

package/dist/lingua-react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lingua-react.cjs","sources":["../src/useTranslations.ts"],"sourcesContent":["import { usePage } from '@inertiajs/react';\n\ninterface LinguaData {\n  locale: string;\n  locales: string[];\n  translations: Record<string, any>;\n}\n\nexport function useTranslations() {\n  const { props } = usePage<{ lingua?: LinguaData; [key: string]: unknown }>();\n  const lingua = props.lingua;\n\n  const __ = (key: string, replacements?: Record<string, string | number>): string => {\n    const keys = key.split('.');\n    let value: any = lingua?.translations;\n    \n    for (const k of keys) {\n      if (value === undefined || value === null) break;\n      value = value[k];\n    }\n    \n    if (typeof value !== 'string') return key;\n    \n    if (replacements) {\n      return Object.entries(replacements).reduce(\n        (str, [k, v]) => str.replace(new RegExp(`:${k}`, 'g'), String(v)),\n        value\n      );\n    }\n    \n    return value;\n  };\n\n  return {\n    __,\n    locale: lingua?.locale ?? 'en',\n    locales: lingua?.locales ?? ['en'],\n  };\n}\n"],"names":["useTranslations","props","usePage","lingua","key","replacements","keys","value","k","str","v"],"mappings":"oHAQO,SAASA,GAAkB,CAChC,KAAM,CAAE,MAAAC,CAAA,EAAUC,UAAA,EACZC,EAASF,EAAM,OAuBrB,MAAO,CACL,GAtBS,CAACG,EAAaC,IAA2D,CAClF,MAAMC,EAAOF,EAAI,MAAM,GAAG,EAC1B,IAAIG,EAAaJ,GAAA,YAAAA,EAAQ,aAEzB,UAAWK,KAAKF,EAAM,CACpB,GAA2BC,GAAU,KAAM,MAC3CA,EAAQA,EAAMC,CAAC,CACjB,CAEA,OAAI,OAAOD,GAAU,SAAiBH,EAElCC,EACK,OAAO,QAAQA,CAAY,EAAE,OAClC,CAACI,EAAK,CAACD,EAAGE,CAAC,IAAMD,EAAI,QAAQ,IAAI,OAAO,IAAID,CAAC,GAAI,GAAG,EAAG,OAAOE,CAAC,CAAC,EAChEH,CAAA,EAIGA,CACT,EAIE,QAAQJ,GAAA,YAAAA,EAAQ,SAAU,KAC1B,SAASA,GAAA,YAAAA,EAAQ,UAAW,CAAC,IAAI,CAAA,CAErC"}

package/dist/lingua-react.js

@@ -0,0 +1,24 @@
+import { usePage as i } from "@inertiajs/react";
+function u() {
+  const { props: s } = i(), e = s.lingua;
+  return {
+    __: (r, n) => {
+      const c = r.split(".");
+      let t = e == null ? void 0 : e.translations;
+      for (const o of c) {
+        if (t == null) break;
+        t = t[o];
+      }
+      return typeof t != "string" ? r : n ? Object.entries(n).reduce(
+        (o, [l, f]) => o.replace(new RegExp(`:${l}`, "g"), String(f)),
+        t
+      ) : t;
+    },
+    locale: (e == null ? void 0 : e.locale) ?? "en",
+    locales: (e == null ? void 0 : e.locales) ?? ["en"]
+  };
+}
+export {
+  u as useTranslations
+};
+//# sourceMappingURL=lingua-react.js.map

package/dist/lingua-react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lingua-react.js","sources":["../src/useTranslations.ts"],"sourcesContent":["import { usePage } from '@inertiajs/react';\n\ninterface LinguaData {\n  locale: string;\n  locales: string[];\n  translations: Record<string, any>;\n}\n\nexport function useTranslations() {\n  const { props } = usePage<{ lingua?: LinguaData; [key: string]: unknown }>();\n  const lingua = props.lingua;\n\n  const __ = (key: string, replacements?: Record<string, string | number>): string => {\n    const keys = key.split('.');\n    let value: any = lingua?.translations;\n    \n    for (const k of keys) {\n      if (value === undefined || value === null) break;\n      value = value[k];\n    }\n    \n    if (typeof value !== 'string') return key;\n    \n    if (replacements) {\n      return Object.entries(replacements).reduce(\n        (str, [k, v]) => str.replace(new RegExp(`:${k}`, 'g'), String(v)),\n        value\n      );\n    }\n    \n    return value;\n  };\n\n  return {\n    __,\n    locale: lingua?.locale ?? 'en',\n    locales: lingua?.locales ?? ['en'],\n  };\n}\n"],"names":["useTranslations","props","usePage","lingua","key","replacements","keys","value","k","str","v"],"mappings":";AAQO,SAASA,IAAkB;AAChC,QAAM,EAAE,OAAAC,EAAA,IAAUC,EAAA,GACZC,IAASF,EAAM;AAuBrB,SAAO;AAAA,IACL,IAtBS,CAACG,GAAaC,MAA2D;AAClF,YAAMC,IAAOF,EAAI,MAAM,GAAG;AAC1B,UAAIG,IAAaJ,KAAA,gBAAAA,EAAQ;AAEzB,iBAAWK,KAAKF,GAAM;AACpB,YAA2BC,KAAU,KAAM;AAC3C,QAAAA,IAAQA,EAAMC,CAAC;AAAA,MACjB;AAEA,aAAI,OAAOD,KAAU,WAAiBH,IAElCC,IACK,OAAO,QAAQA,CAAY,EAAE;AAAA,QAClC,CAACI,GAAK,CAACD,GAAGE,CAAC,MAAMD,EAAI,QAAQ,IAAI,OAAO,IAAID,CAAC,IAAI,GAAG,GAAG,OAAOE,CAAC,CAAC;AAAA,QAChEH;AAAA,MAAA,IAIGA;AAAA,IACT;AAAA,IAIE,SAAQJ,KAAA,gBAAAA,EAAQ,WAAU;AAAA,IAC1B,UAASA,KAAA,gBAAAA,EAAQ,YAAW,CAAC,IAAI;AAAA,EAAA;AAErC;"}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export interface LinguaProps {
+    locale: string;
+    locales: string[];
+    translations: Record<string, any>;
+}
+export type TranslateFunction = (key: string, replacements?: Record<string, string | number>) => string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,MAAM,CAAC"}

package/dist/useTranslations.d.ts

@@ -0,0 +1,6 @@
+export declare function useTranslations(): {
+    __: (key: string, replacements?: Record<string, string | number>) => string;
+    locale: string;
+    locales: string[];
+};
+//# sourceMappingURL=useTranslations.d.ts.map

package/dist/useTranslations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTranslations.d.ts","sourceRoot":"","sources":["../src/useTranslations.ts"],"names":[],"mappings":"AAQA,wBAAgB,eAAe;cAIZ,MAAM,iBAAiB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAG,MAAM;;;EA0BjF"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@tooinfinity/lingua-react",
+  "version": "1.0.0",
+  "description": "React bindings for Laravel Lingua - translations made easy with Inertia.js",
+  "type": "module",
+  "main": "./dist/lingua-react.cjs",
+  "module": "./dist/lingua-react.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/lingua-react.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/lingua-react.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly",
+    "dev": "vite build --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "laravel",
+    "lingua",
+    "react",
+    "inertia",
+    "i18n",
+    "translations",
+    "localization"
+  ],
+  "author": "TooInfinity",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tooinfinity/lingua-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tooinfinity/lingua-react/issues"
+  },
+  "homepage": "https://github.com/tooinfinity/lingua-react#readme",
+  "peerDependencies": {
+    "@inertiajs/react": "^1.0.0 || ^2.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@inertiajs/react": "^2.0.0",
+    "@types/node": "^25.0.8",
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0"
+  }
+}