@genrwork/laravel-i18next 0.1.0

package/README.md

@@ -0,0 +1,367 @@
+# laravel-i18next
+
+Use your **Laravel** translation files with [i18next](https://www.i18next.com) in **React**, **Vue 3** or **Svelte** (4 or 5), translated exactly like [Laravel Localization](https://laravel.com/docs/localization) does.
+
+Each Laravel language file becomes its own **i18next namespace**: `lang/{locale}.json` is the default namespace, and each `lang/{locale}/{namespace}.php` file (auth, validation, your own...) becomes a namespace of the same name — nested any number of levels deep, too (`lang/{locale}/{ns1}/{ns2}.php` → namespace `ns1/ns2`). Nothing is merged into one big bundle, so components only load and depend on the namespaces they actually use.
+
+The Vite plugin can also read from **more than one directory**, in a fixed priority order — e.g. a hand-written frontend-only JSON catalog first, PHP translations second. A namespace present in several of these sources is merged per key, higher priority winning, so a project can move a namespace's strings out of PHP into hand-written JSON one string at a time without breaking the ones not yet moved. See [Sources and precedence](#sources-and-precedence).
+
+Components use their framework's own i18next bindings: `useTranslation()` (React, Vue) or the store-based `useTranslation()` this package provides for Svelte. This package supplies:
+
+- `LaravelBackend` and `LaravelFormat`, the i18next plugins doing the work: loading the namespaced language files (merging several sources per key when configured), and translating like Laravel (`:name` replacements, `trans_choice()` pluralization).
+- A provider per framework — `LaravelReactI18nProvider` (`/react`), `laravelVueI18n` (`/vue`), `setLaravelI18nContext`/`useTranslation` (`/svelte`) — built on top of the two plugins above, SSR and hydration ready.
+- A Vite plugin (`/vite`) turning PHP translations into JSON, and serving one or more sources of language files to the provider through a virtual module.
+
+## Requirements
+
+- One of: React 18/19 + react-i18next >= 15, Vue 3.4+, Svelte 4 or 5
+- i18next >= 24
+- Vite >= 5 (optional; the framework bindings work with any bundler, only `/vite` needs Vite)
+
+## Installation
+
+```sh
+npm install @genrwork/laravel-i18next i18next
+# React
+npm install react-i18next
+# Vue
+npm install i18next-vue
+# Svelte: nothing else to install
+```
+
+## Setup
+
+### 1. Vite plugin
+
+`vite.config.ts`:
+
+```ts
+import i18n from '@genrwork/laravel-i18next/vite'; // <-- add this
+
+export default defineConfig({
+  plugins: [
+    laravel({ input: ['resources/css/app.css', 'resources/js/app.ts'], refresh: true }),
+    react(), // or vue(), or svelte()
+    i18n(), // <-- add this
+  ],
+});
+```
+
+While Vite runs, the plugin converts every `.php` file found under a source directory (at any depth) into a sibling `.json` file (regenerated when the PHP file changes, deleted when the build ends). Keep them out of git:
+
+```
+lang/*/*.json
+Modules/*/lang/*/*.json
+```
+
+The `sources` option is an ordered list of directories, **highest priority first**; each may hold hand-written `.json` files, `.php` files, or both (but not both for the same namespace — a hand-written file always wins where present, so don't shadow one with a same-named PHP file in the same directory). One `*` wildcard segment is allowed per entry, expanded against every matching directory that exists, e.g. `Modules/*/lang`. Defaults to `['lang']`, matching a single Laravel app with no other sources.
+
+```ts
+i18n({
+  sources: [
+    'resources/js/lang', // hand-written, frontend-only strings -- highest priority
+    'Modules/*/lang', // this app's own modules' PHP translations
+    'lang', // the app's own PHP translations
+  ],
+});
+```
+
+The plugin also serves the language files as `virtual:laravel-i18next/files`: an array, one entry per configured source in the same order, each eagerly loaded in server code (so SSR renders translated) and lazily loaded in client code, one chunk per namespace. Declare its type next to Vite's, e.g. in `resources/js/types/vite-env.d.ts`:
+
+```ts
+/// <reference types="vite/client" />
+/// <reference types="@genrwork/laravel-i18next/client" />
+```
+
+Without the Vite plugin, build the same structure yourself: an array of `import.meta.glob('/lang/**/*.json')` calls (lazy) or `import.meta.glob('/lang/**/*.json', { eager: true })` calls (eager), one per source, in priority order — see [Namespaces](#namespaces) and [Sources and precedence](#sources-and-precedence). A single `import.meta.glob()` result (not wrapped in an array) is also accepted, as a one-source project.
+
+### 2. Share the locale
+
+`app/Http/Middleware/HandleInertiaRequests.php` (or any equivalent for your setup):
+
+```php
+public function share(Request $request): array
+{
+    return [
+        ...parent::share($request),
+        'locale' => app()->getLocale(),
+        // ...
+    ];
+}
+```
+
+### 3. Framework setup
+
+<details open><summary><strong>React</strong> (Inertia v3, <code>withApp</code>)</summary>
+
+`resources/js/app.tsx`:
+
+```tsx
+import { createInertiaApp } from '@inertiajs/react';
+import { LaravelReactI18nProvider } from '@genrwork/laravel-i18next/react';
+import files from 'virtual:laravel-i18next/files';
+
+void createInertiaApp({
+  strictMode: true,
+  withApp(app, { page }) {
+    return (
+      <LaravelReactI18nProvider locale={page.props.locale as string} fallbackLocale="en" files={files}>
+        {app}
+      </LaravelReactI18nProvider>
+    );
+  },
+});
+```
+
+</details>
+
+<details><summary><strong>React</strong> (Inertia v2, <code>setup</code>)</summary>
+
+`resources/js/app.tsx`:
+
+```tsx
+import { createInertiaApp } from '@inertiajs/react';
+import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
+import { hydrateRoot } from 'react-dom/client';
+import { LaravelReactI18nProvider } from '@genrwork/laravel-i18next/react';
+import files from 'virtual:laravel-i18next/files';
+
+createInertiaApp({
+  resolve: (name) => resolvePageComponent(`./pages/${name}.tsx`, import.meta.glob('./pages/**/*.tsx')),
+  setup({ el, App, props }) {
+    // Without SSR: createRoot(el).render(...)
+    hydrateRoot(
+      el,
+      <LaravelReactI18nProvider locale={props.initialPage.props.locale as string} fallbackLocale="en" files={files}>
+        <App {...props} />
+      </LaravelReactI18nProvider>
+    );
+  },
+});
+```
+
+With SSR, `resources/js/ssr.tsx` follows the same shape with `render: ReactDOMServer.renderToString` and `createServer()`, as in [Laravel's own SSR guide](https://inertiajs.com/server-side-rendering).
+
+</details>
+
+<details><summary><strong>Vue 3</strong></summary>
+
+`resources/js/app.ts`:
+
+```ts
+import { createInertiaApp } from '@inertiajs/vue3';
+import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
+import { createApp, h } from 'vue';
+import { laravelVueI18n } from '@genrwork/laravel-i18next/vue';
+import files from 'virtual:laravel-i18next/files';
+
+createInertiaApp({
+  resolve: (name) => resolvePageComponent(`./pages/${name}.vue`, import.meta.glob('./pages/**/*.vue')),
+  setup({ el, App, props, plugin }) {
+    createApp({ render: () => h(App, props) })
+      .use(plugin)
+      .use(laravelVueI18n({ locale: props.initialPage.props.locale as string, fallbackLocale: 'en', files }))
+      .mount(el);
+  },
+});
+```
+
+For SSR, use `createSSRApp` instead of `createApp` in `resources/js/ssr.ts`, as in [Inertia's own Vue 3 SSR guide](https://inertiajs.com/server-side-rendering) — everything else stays the same.
+
+In components: `import { useTranslation } from '@genrwork/laravel-i18next/vue'` (re-exported from `i18next-vue`), or the global `$t` / `$i18next`.
+
+</details>
+
+<details><summary><strong>Svelte</strong> (4 or 5)</summary>
+
+`resources/js/app.ts` (with [`@inertiajs/svelte`](https://inertiajs.com)):
+
+```ts
+import { createInertiaApp } from '@inertiajs/svelte';
+import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
+import files from 'virtual:laravel-i18next/files';
+import App from './App.svelte';
+
+createInertiaApp({
+  resolve: (name) => resolvePageComponent(`./pages/${name}.svelte`, import.meta.glob('./pages/**/*.svelte')),
+  setup({ el, App: Page, props }) {
+    new App({ target: el, props: { Page, props, files } });
+  },
+});
+```
+
+`App.svelte` (top of the component tree — the locale prop is whatever Inertia passes through `props`):
+
+```svelte
+<script lang="ts">
+  import { setLaravelI18nContext } from '@genrwork/laravel-i18next/svelte';
+
+  export let Page;
+  export let props;
+  export let files;
+
+  setLaravelI18nContext({ locale: props.locale, fallbackLocale: 'en', files });
+</script>
+
+<svelte:component this={Page} {...props} />
+```
+
+In any child component:
+
+```svelte
+<script lang="ts">
+  import { useTranslation } from '@genrwork/laravel-i18next/svelte';
+
+  const { t } = useTranslation('auth');
+</script>
+
+<p>{$t('failed')}</p>
+```
+
+</details>
+
+### Following locale changes
+
+The framework setup above only runs once, when the page loads. When Laravel shares another locale after a visit (e.g. the user switched language), change the language from a layout component. React:
+
+```tsx
+import { usePage } from '@inertiajs/react';
+import { useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+
+export default function AppLayout({ children }: { children: React.ReactNode }) {
+  const { locale } = usePage<{ locale: string }>().props;
+  const { i18n } = useTranslation();
+
+  useEffect(() => {
+    if (i18n.language !== locale) i18n.changeLanguage(locale);
+  }, [i18n, locale]);
+
+  return children;
+}
+```
+
+Vue and Svelte follow the same idea: watch the shared `locale` prop and call `i18next.changeLanguage(locale)` (Vue: `const { i18next } = useTranslation()`; Svelte: the `i18next` instance returned by `setLaravelI18nContext()`/`useTranslation()`).
+
+## Sources and precedence
+
+With more than one `sources` entry, the same `(locale, namespace)` pair can come from several places at once. They are merged **per key**, highest-priority source winning, rather than one source replacing another wholesale:
+
+```
+resources/js/lang/es/settings.json   { "Save": "Guardar" }
+lang/es/settings.php                 ['Save' => 'Guardar (antiguo)', 'profile_updated' => 'Perfil actualizado.']
+
+→ namespace "settings", locale "es":
+  Save            -> "Guardar"               (from the higher-priority source)
+  profile_updated -> "Perfil actualizado."   (only in the lower-priority source, resolves from there)
+```
+
+This is what lets a namespace migrate from PHP to hand-written JSON one string at a time: move a key, and every key not yet moved keeps resolving from PHP.
+
+The merge is a **shallow** merge over already-flattened, dotted keys (`sub_level1.text`, not `{ sub_level1: { text: ... } }`) — since a PHP file is flattened before it ever becomes JSON, this shallow merge is exactly the deep merge Laravel itself performs over the original nested arrays; no separate deep-merge step is needed.
+
+Two things worth knowing:
+
+- **Ties within one source resolve by path order** (alphabetical, as `import.meta.glob()` returns them) — if a wildcard source matches two directories that both produce the very same `(locale, namespace)` pair (e.g. two modules that happen to define an identically-named namespace), the alphabetically-first path wins, silently. Prefixing a module's own namespaces with its name avoids this in practice.
+- **A namespace segment that itself looks like a locale code is misread as the locale** — see the note on `classify()` in `src/utils/recognizer.ts`. No namespace in a typical app looks like a locale code, so this is a documented edge case, not something the library tries to solve.
+
+## Namespaces
+
+Every Laravel language file is its own namespace:
+
+```
+lang/
+  en.json          → default namespace ("translation")
+  en/
+    auth.php       → "auth" namespace
+    validation.php → "validation" namespace
+    teams/
+      roles.php    → "teams/roles" namespace (nested any number of levels)
+  it/
+    auth.php       → "auth" namespace
+```
+
+`import.meta.glob('/lang/**/*.json')` (or the `virtual:laravel-i18next/files` module) must be **recursive** so it picks up all of these. A component requests a namespace the same way it would for any i18next app:
+
+```tsx
+const { t } = useTranslation('auth'); // React
+const { t } = useTranslation('auth'); // Vue (i18next-vue)
+const { t } = useTranslation('auth'); // Svelte
+```
+
+Namespaces are not merged with each other: `t('failed')` inside the `auth` namespace only sees `auth.php`'s keys — even with several `sources`, a namespace only ever merges with the SAME namespace from another source (see [Sources and precedence](#sources-and-precedence)), never with a different one. Request several namespaces at once (`useTranslation(['translation', 'auth'])` in React/Vue) to use more than one from the same component — list the default namespace **first** if you call `t()` without an explicit `ns`, since react-i18next/i18next-vue resolve unscoped calls against the first namespace in that list. Passing `{ ns: 'auth' }` per call works regardless of order, and is what the Svelte binding always does (its `useTranslation()` is scoped to one namespace per call).
+
+## Provider / plugin options
+
+`files`, `locale` and `fallbackLocale` are the same across React, Vue and Svelte:
+
+- `files` _(required)_: `virtual:laravel-i18next/files` (an array, one entry per configured source), or your own single `import.meta.glob('/lang/**/*.json')` (lazy) / `import.meta.glob('/lang/**/*.json', { eager: true })` (eager) — a bare map behaves exactly like a one-source array.
+- `locale` _(optional)_: defaults to the `<html lang="">` attribute, or `en`.
+- `fallbackLocale` _(optional)_: used when a translation is missing, or when a namespace has no file for `locale`. Defaults to the `<html lang="">` attribute, or `en`.
+
+Every provider/plugin instance creates its own i18next instance, so concurrent SSR requests never share a language. Eagerness is all-or-nothing **across every non-empty source**: with every source eager, every known namespace is preloaded and translated on the first render, synchronously — this is what the Vite plugin always emits for SSR, and what a hand-rolled config should match to keep SSR synchronous. With any source lazy, a namespace is fetched the first time a component requests it (merging still waits for every source's candidate to resolve) — in React, requesting components suspend meanwhile (wrap them in `<Suspense>`, which the provider already does around its children); in Vue and Svelte, use the `ready` value (`i18next-vue` re-renders once loaded; the Svelte `useTranslation()` returns a `ready` store) to show a loading state instead. The `<html lang="">` attribute is set immediately and kept in sync with the language.
+
+## Usage
+
+### Translating
+
+`lang/pt.json` (default namespace):
+
+```json
+{
+  "Welcome!": "Bem-vindo!",
+  "Welcome, :name!": "Bem-vindo, :name!"
+}
+```
+
+```tsx
+const { t } = useTranslation();
+
+t('Welcome!'); // Bem-vindo!
+t('Welcome, :name!', { name: 'Francisco' }); // Bem-vindo, Francisco!
+t('Welcome, :NAME!', { name: 'Francisco' }); // Bem-vindo, FRANCISCO!
+t('Some untranslated'); // Some untranslated
+```
+
+`lang/pt/auth.php` → `auth` namespace:
+
+```tsx
+const { t } = useTranslation('auth');
+
+t('failed'); // PHP translation from lang/pt/auth.php's 'failed' key
+```
+
+A missing (or empty) translation is looked up in the fallback language, then the key itself is returned.
+
+i18next `{{name}}` interpolation and `$t()` nesting are not applied. Replacements named like an i18next option (`lng`, `ns`, `context`, `defaultValue`...) must be given in `replace`: `t('Hello :lng', { replace: { lng: 'PHP' } })`.
+
+### Pluralization
+
+Pass the number as `count`:
+
+`lang/pt/fruits.php`:
+
+```php
+<?php
+return [
+  'apple_count' => ':count apple|:count apples',
+  'none_some_many' => '{0} There are none|[1,19] There are some|[20,*] There are many',
+];
+```
+
+```tsx
+const { t } = useTranslation('fruits');
+
+t('apple_count', { count: 1 }); // 1 apple
+t('none_some_many', { count: 19 }); // There are some
+```
+
+Segments without an explicit range are picked with the plural rules of the language the message actually resolved in — the current language, or the fallback language when the message itself came from there, like Laravel does. This is deliberately not just "does the namespace have a file for the current language": with several `sources`, a namespace can end up with SOME content for a language (enough to make `hasResourceBundle()` true) while the specific message being pluralized still came from the fallback — pluralization follows the message, not the namespace. `_one` / `_other` suffixed keys are not used.
+
+## Credits
+
+- The translation behavior (replacements, pluralization) mirrors Laravel's own [`__()`](https://laravel.com/docs/localization) and `trans_choice()`.
+
+## License
+
+MIT &copy; GenrWork

package/client.d.ts

@@ -0,0 +1,12 @@
+declare module 'virtual:laravel-i18next/files' {
+  import type { LocaleFiles } from '@genrwork/laravel-i18next';
+
+  /**
+   * Laravel language files, one entry per configured `sources` (see the
+   * `/vite` plugin's options), highest priority first. Each entry is loaded
+   * eagerly on the server (SSR) and lazily on the client.
+   */
+  const files: LocaleFiles[];
+
+  export default files;
+}

package/dist/index.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var createI18n = require('./shared/create-i18n-WsDK4Z8L.cjs');
+require('i18next');
+
+
+
+exports.LaravelBackend = createI18n.LaravelBackend;
+exports.LaravelFormat = createI18n.LaravelFormat;
+exports.createI18n = createI18n.createI18n;
+exports.documentLocale = createI18n.documentLocale;
+exports.syncDocumentLang = createI18n.syncDocumentLang;

package/dist/index.mjs

@@ -0,0 +1,2 @@
+export { L as LaravelBackend, a as LaravelFormat, c as createI18n, d as documentLocale, s as syncDocumentLang } from './shared/create-i18n-BSEwKsCX.mjs';
+import 'i18next';

package/dist/react.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var reactI18next = require('react-i18next');
+var createI18n = require('./shared/create-i18n-WsDK4Z8L.cjs');
+require('i18next');
+
+/**
+ * Provides an i18next instance translating Laravel language files to react-i18next.
+ *
+ * Every provider owns its instance, so concurrent SSR requests do not share a language.
+ * With eager files, every namespace is preloaded and translated on the first render.
+ * While a lazy namespace loads, the children suspend, which keeps server-rendered
+ * HTML in place until it can be hydrated.
+ */ function LaravelReactI18nProvider({ children, files, locale, fallbackLocale }) {
+    const [i18n] = react.useState(()=>createI18n.createI18n({
+            files,
+            locale,
+            fallbackLocale
+        }));
+    react.useEffect(()=>{
+        if (locale && locale !== i18n.language) i18n.changeLanguage(locale);
+    }, [
+        i18n,
+        locale
+    ]);
+    react.useEffect(()=>createI18n.syncDocumentLang(i18n), [
+        i18n
+    ]);
+    return jsxRuntime.jsx(reactI18next.I18nextProvider, {
+        i18n: i18n,
+        children: jsxRuntime.jsx(react.Suspense, {
+            fallback: null,
+            children: children
+        })
+    });
+}
+
+exports.LaravelReactI18nProvider = LaravelReactI18nProvider;

package/dist/react.mjs

@@ -0,0 +1,38 @@
+import { jsx } from 'react/jsx-runtime';
+import { useState, useEffect, Suspense } from 'react';
+import { I18nextProvider } from 'react-i18next';
+import { c as createI18n, s as syncDocumentLang } from './shared/create-i18n-BSEwKsCX.mjs';
+import 'i18next';
+
+/**
+ * Provides an i18next instance translating Laravel language files to react-i18next.
+ *
+ * Every provider owns its instance, so concurrent SSR requests do not share a language.
+ * With eager files, every namespace is preloaded and translated on the first render.
+ * While a lazy namespace loads, the children suspend, which keeps server-rendered
+ * HTML in place until it can be hydrated.
+ */ function LaravelReactI18nProvider({ children, files, locale, fallbackLocale }) {
+    const [i18n] = useState(()=>createI18n({
+            files,
+            locale,
+            fallbackLocale
+        }));
+    useEffect(()=>{
+        if (locale && locale !== i18n.language) i18n.changeLanguage(locale);
+    }, [
+        i18n,
+        locale
+    ]);
+    useEffect(()=>syncDocumentLang(i18n), [
+        i18n
+    ]);
+    return jsx(I18nextProvider, {
+        i18n: i18n,
+        children: jsx(Suspense, {
+            fallback: null,
+            children: children
+        })
+    });
+}
+
+export { LaravelReactI18nProvider };