@genrwork/laravel-i18next 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Use your **Laravel** translation files with [i18next](https://www.i18next.com) in **React**, **Vue 3** or **Svelte** (4 or 5). PHP files keep [Laravel Localization](https://laravel.com/docs/localization)'s conventions and are converted to i18next JSON at build time, so the browser only ever sees, and your frontend code only ever writes, plain i18next.
 
 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.
 
@@ -8,9 +8,42 @@ The Vite plugin can also read from **more than one directory**, in a fixed prior
 
 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.
+- `LaravelBackend`, the i18next backend loading the namespaced language files (merging several sources per key when configured), plus `laravelOptions` and `registerCaseFormats()`, the few i18next options and formats Laravel-style translations need.
+- A provider per framework — `LaravelReactI18nProvider` (`/react`), `laravelVueI18n` (`/vue`), `setLaravelI18nContext`/`useTranslation` (`/svelte`) — built on top of them, SSR and hydration ready.
+- A Vite plugin (`/vite`) converting PHP translations into i18next JSON, and serving one or more sources of language files to the provider through a virtual module.
+
+## Two formats, one meeting point
+
+Everything PHP is written the **Laravel** way, and converted for you. Everything JSON is written the **i18next** way, and read as is:
+
+| | PHP (`lang/{locale}/*.php`) | JSON (hand-written) |
+| --- | --- | --- |
+| placeholder | `:name` | `{{name}}` |
+| upper / capitalized | `:NAME` / `:Name` | `{{name, uppercase}}` / `{{name, capitalize}}` |
+| plural forms | `'one apple\|:count apples'` | `"apples_one"`, `"apples_other"` (`_zero`, `_two`, `_few`, `_many` where the language has them) |
+| a count of 0 | `'{0} none\|...'` | `"apples_zero"` |
+| nesting a key | nested arrays, flattened to `a.b.c` | flat keys, or nested objects |
+
+The converted file is what the app loads, so for the message above the browser gets:
+
+```json
+{
+  "greeting": "Hello {{name}}",
+  "apples": "one apple|{{count}} apples",
+  "apples_one": "one apple",
+  "apples_other": "{{count}} apples"
+}
+```
+
+and the frontend calls `t('greeting', { name })` and `t('apples', { count })`, exactly like any other i18next project. Laravel keeps using the PHP file, untouched, through `trans()` and `trans_choice()`.
+
+How a PHP message is converted, and what it cannot do:
+
+- A placeholder is a colon followed by a name that does not hang on a word before it: `:name`, `(:count)`, but not `https://`, `10:30` or `Note:this`. Nothing is left to a regex at runtime, so `:to` never touches `:total`.
+- `:NAME` and `:Name` are read as the upper-cased and capitalized forms of `name`, as Laravel does. A placeholder that is *itself* written in capitals (`:ID`) therefore becomes `{{id, uppercase}}`.
+- Every message containing a `|` is a plural message. The raw text stays under the plain key too, which is what `trans()` gives without a count; the plural forms come from asking Laravel's own rules for whole counts and grouping them by the plural category of the language of the file (`lang/{locale}/`). A message Laravel answers differently *within* one category (`[2,19]` next to `[20,*]` in English) cannot be written as i18next plural keys: the build fails and names the key instead of translating it wrongly.
+- `{{` in a PHP message is i18next interpolation syntax; write it in a hand-written JSON source if you need the text.
+- Laravel's own `lang/{locale}.json` files are not converted -- they are read as i18next JSON like every other `.json` file. Keep frontend strings in a source of their own (see [Sources and precedence](#sources-and-precedence)).
 
 ## Requirements
 
@@ -47,26 +80,28 @@ export default defineConfig({
 });
 ```
 
-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:
+While Vite runs, the plugin converts every `.php` file found under a source directory (at any depth) into a sibling i18next `.json` file (regenerated when the PHP file changes, deleted when the build ends). Keep them out of git:
 
 ```
 lang/*/*.json
-Modules/*/lang/*/*.json
+# and, for a wildcard source such as packages/*/lang (see below):
+packages/*/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.
+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. `packages/*/lang` for an app split into modules. 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`:
+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. Two more options: `ssr` (`'eager'` by default, or `'lazy'` for large projects -- see [Large projects](#large-projects-lazy-on-the-server-too)) and `detectNamespaces` (`true` by default: tells [`preloadI18n()`](#loading-without-gaps) which namespaces each module uses).
+
+Declare its type next to Vite's, e.g. in `resources/js/types/vite-env.d.ts`:
 
 ```ts
 /// <reference types="vite/client" />
@@ -220,6 +255,20 @@ In any child component:
 
 </details>
 
+### i18next options
+
+The providers initialize i18next with `laravelOptions`: no key or namespace separator (Laravel keys are flat and contain dots and colons), an empty message counts as missing and falls back, and interpolated values are not escaped (React, Vue and Svelte already escape what they render; Laravel's `:name` never escaped either). They also register the `uppercase`, `lowercase` and `capitalize` formats the converted `:NAME` / `:Name` need. Setting i18next up by hand:
+
+```ts
+import i18next from 'i18next';
+import { LaravelBackend, laravelOptions, registerCaseFormats } from '@genrwork/laravel-i18next';
+
+const i18n = i18next.createInstance();
+
+await i18n.use(LaravelBackend).init({ ...laravelOptions, lng: 'pt', backend: { files } });
+registerCaseFormats(i18n);
+```
+
 ### 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:
@@ -243,6 +292,46 @@ export default function AppLayout({ children }: { children: React.ReactNode }) {
 
 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()`).
 
+## Loading without gaps
+
+Translations are chunks, like pages: with lazy files a namespace is downloaded the first time something needs it. If that happens while rendering, the framework suspends and shows a fallback -- a blank gap on every visit to a page whose namespaces are not there yet, exactly what Inertia avoids for the page component itself by loading it *before* swapping to it. Do the same for translations:
+
+```ts
+import { withI18nPreload } from '@genrwork/laravel-i18next';
+import files from 'virtual:laravel-i18next/files';
+
+createInertiaApp({
+  resolve: withI18nPreload((name) => resolvePageComponent(`./pages/${name}.tsx`, pages), {
+    files,
+    fallbackLocale: 'en',
+    // The language the page is shown in: whatever your server shares with every page.
+    locale: (page) => page.props.locale as string,
+  }),
+  // ...
+});
+```
+
+`withI18nPreload()` resolves the page, then loads -- for the language `locale(page)` returns and the fallback language -- every namespace the page uses, and only then hands the page back. Which namespaces? The Vite plugin adds a tiny declaration to every module calling `useTranslation('ns')` (also `withTranslation`, `<Trans ns="ns">`, `{ ns: 'ns' }`); evaluating a page evaluates everything it statically imports, so by the time it is resolved the declarations of the page, its layout and its components are all in, however deeply nested and with nothing to write by hand. A namespace requested through a variable is invisible to the plugin: call `declareNamespaces(['ns'])` for it, or pass `namespaces: ['ns']` (or `'*'` for every namespace) to `withI18nPreload()`. Resolving the page that is already on screen in another language (a language setting saved, a language chosen through a link) loads, by default, everything declared, like any other page. Pass `onLanguageSwitch: 'rendered'` to load only the namespaces that page has rendered with (react-i18next records them) and to stop i18next from re-loading every namespace it ever loaded: a session that visited many pages then downloads a few catalogs for the switch instead of all of them, and a namespace left out is loaded, before the page renders, when a page that needs it is visited. It is only right when a page renders the same namespaces in every language and nothing it opens later needs one it has not shown yet -- otherwise that namespace suspends until it arrives. Outside react-i18next it has no effect. A component lazy-loaded *by* the page (`React.lazy`) is its own chunk with its own declarations: its namespaces load when it does, and, like the component itself, it shows its own loading state (`fallback` prop of `<LaravelReactI18nProvider>`).
+
+What this gives you, in the browser and on the server alike:
+
+- the first render is translated -- the provider finds everything in memory and is ready synchronously, with or without SSR;
+- a client-side visit never blanks: the previous page stays until the next one, translations included, can be shown whole;
+- switching language costs the same: the new language is loaded while the page that switches to it resolves, so it appears with the page;
+- only what a page needs is downloaded, never every namespace of every language.
+
+`preloadI18n({ files, locale, fallbackLocale, namespaces })` is the function underneath, for a router that is not Inertia's. It returns once the modules are loaded, and already-loaded ones cost nothing.
+
+### Large projects: lazy on the server too
+
+By default the server bundle holds every language file (`ssr: 'eager'`), which keeps SSR free of any step of its own and is right for a few languages. With many languages or namespaces, make the server lazy as well:
+
+```ts
+i18n({ ssr: 'lazy', sources: [/* ... */] });
+```
+
+Each catalog becomes a chunk of the server build, imported the first time a request needs it and kept by Node afterwards; the server bundle does not grow with the number of languages. This needs `withI18nPreload()` (or `preloadI18n()`) in front of the render, as above: SSR cannot wait for a chunk while rendering, so it must be there before. Without it, a lazy server renders untranslated keys.
+
 ## 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:
@@ -258,7 +347,7 @@ lang/es/settings.php                 ['Save' => 'Guardar (antiguo)', 'profile_up
 
 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.
+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. A hand-written JSON source overriding a plural message overrides it by its i18next keys (`apples_one`, `apples_other`).
 
 Two things worth knowing:
 
@@ -299,18 +388,18 @@ Namespaces are not merged with each other: `t('failed')` inside the `auth` names
 - `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.
+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 -- what the Vite plugin emits for SSR by default (`ssr: 'eager'`). With lazy files, only the namespaces declared by the modules evaluated so far are loaded up front, and any other one when it is first needed (merging still waits for every source's candidate to resolve): in React the requesting components suspend meanwhile, showing the provider's `fallback` prop (nothing by default; the provider already wraps its children in `<Suspense>`); 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. Preload them and nothing waits at all -- see [Loading without gaps](#loading-without-gaps). The `<html lang="">` attribute is set immediately and kept in sync with the language.
 
 ## Usage
 
 ### Translating
 
-`lang/pt.json` (default namespace):
+`lang/pt.json` (default namespace), i18next JSON:
 
 ```json
 {
   "Welcome!": "Bem-vindo!",
-  "Welcome, :name!": "Bem-vindo, :name!"
+  "welcome_name": "Bem-vindo, {{name}}!"
 }
 ```
 
@@ -318,26 +407,24 @@ Every provider/plugin instance creates its own i18next instance, so concurrent S
 const { t } = useTranslation();
 
 t('Welcome!'); // Bem-vindo!
-t('Welcome, :name!', { name: 'Francisco' }); // Bem-vindo, Francisco!
-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:
+`lang/pt/auth.php` → `auth` namespace, converted from PHP:
 
 ```tsx
 const { t } = useTranslation('auth');
 
 t('failed'); // PHP translation from lang/pt/auth.php's 'failed' key
+t('throttle', { seconds: 5 }); // its ':seconds' placeholder
 ```
 
-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' } })`.
+A missing (or empty) translation is looked up in the fallback language, then the key itself is returned. The `{{name}}` interpolation, `$t()` nesting, `context` and every other i18next feature work as documented by i18next.
 
 ### Pluralization
 
-Pass the number as `count`:
+Pass the number as `count`; i18next picks the `_one` / `_other` (...) key by the plural rules of the language the message resolved in — the current language, or the fallback language when the message itself came from there. That holds with several `sources` too: a namespace can have SOME content for a language while the specific message still comes from the fallback, and pluralization follows the message, not the namespace.
 
 `lang/pt/fruits.php`:
 
@@ -345,7 +432,7 @@ Pass the number as `count`:
 <?php
 return [
   'apple_count' => ':count apple|:count apples',
-  'none_some_many' => '{0} There are none|[1,19] There are some|[20,*] There are many',
+  'none_some_many' => '{0} There are none|{1} There is one|[2,*] There are many',
 ];
 ```
 
@@ -353,15 +440,10 @@ return [
 const { t } = useTranslation('fruits');
 
 t('apple_count', { count: 1 }); // 1 apple
-t('none_some_many', { count: 19 }); // There are some
+t('none_some_many', { count: 0 }); // There are none
+t('none_some_many', { count: 7 }); // There are many
 ```
 
-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/dist/index.cjs

@@ -1,12 +1,134 @@
 'use strict';
 
-var createI18n = require('./shared/create-i18n-WsDK4Z8L.cjs');
+var createI18n = require('./shared/create-i18n-DI7Eog6O.cjs');
+var demand = require('./shared/demand-sbjTXVnl.cjs');
 require('i18next');
 
-
+function unique(values) {
+    return Array.from(new Set(values.filter((value)=>Boolean(value))));
+}
+/**
+ * The language and its base language: `es-MX` is looked up as `es-MX`, then `es`.
+ */ function languagesOf(locale, fallbackLocale) {
+    return unique([
+        locale,
+        locale.split(/[-_]/)[0],
+        fallbackLocale,
+        fallbackLocale === null || fallbackLocale === void 0 ? void 0 : fallbackLocale.split(/[-_]/)[0]
+    ]);
+}
+/**
+ * Load, before anything renders, the translations a page needs.
+ *
+ * With lazy files (the browser, or the server with `ssr: 'lazy'`) a namespace
+ * is a chunk to download, and rendering something that needs a chunk not yet
+ * there means waiting for it: the framework suspends and shows a fallback --
+ * a blank gap, where Inertia would have kept the old page on screen. Inertia
+ * avoids that by loading the next page's component before swapping to it.
+ * This does the same for its translations: call it (see `withI18nPreload()`)
+ * while the page is resolved, and by the time it renders every namespace it
+ * translates with is already in memory, so nothing suspends.
+ *
+ * It loads, for the language and its fallback, the namespaces declared by the
+ * modules evaluated so far -- the page component and everything it statically
+ * imports, which the Vite plugin records -- plus the ones given in
+ * `namespaces`. Loaded modules are cached, so calling it again costs nothing
+ * for what is already there. Live browser instances get the namespaces added,
+ * and the new language too when the page switched it.
+ *
+ * With eager files there is nothing to wait for and it returns at once.
+ */ async function preloadI18n({ files, locale, fallbackLocale, namespaces, declared = true }) {
+    if (!locale) return;
+    const sources = createI18n.toSources(files);
+    const index = createI18n.recognizer(sources);
+    const known = index.getAllNamespaces();
+    const wanted = namespaces === '*' ? known : unique([
+        createI18n.DEFAULT_NAMESPACE,
+        ...declared ? demand.getDeclaredNamespaces() : [],
+        ...namespaces !== null && namespaces !== void 0 ? namespaces : []
+    ]);
+    const needed = wanted.filter((namespace)=>known.includes(namespace));
+    const languages = languagesOf(locale, fallbackLocale);
+    // What a page needs, an instance created next (SSR) must start with too.
+    demand.declareNamespaces(needed);
+    await Promise.all(languages.flatMap((language)=>needed.flatMap((namespace)=>createI18n.resolver(sources, language, namespace))));
+    await Promise.all(demand.getLiveInstances().map((instance)=>loadInto(instance, locale, needed)));
+}
+/**
+ * Give a running instance the namespaces (and the language) a page needs. The
+ * modules are cached by now, so its backend reads them without waiting.
+ */ async function loadInto(instance, locale, namespaces) {
+    if (!instance.isInitialized || namespaces.length === 0) return;
+    await instance.loadNamespaces(namespaces);
+    if (locale !== instance.language) {
+        const missing = namespaces.filter((namespace)=>!instance.hasResourceBundle(locale, namespace));
+        if (missing.length > 0) await instance.reloadResources(languagesOf(locale), missing);
+    }
+}
+/**
+ * Wrap a page resolver so a page never renders before its translations are in
+ * memory -- the same guarantee Inertia gives the page component itself, and
+ * for the same reason: nothing is swapped in until it can be shown whole.
+ *
+ * ```ts
+ * createInertiaApp({
+ *   resolve: withI18nPreload((name) => resolvePageComponent(...), {
+ *     files,
+ *     fallbackLocale: "en",
+ *     locale: (page) => page.props.locale as string,
+ *   }),
+ * });
+ * ```
+ *
+ * The page component is resolved first, which evaluates it and everything it
+ * imports and so declares their namespaces; then those are loaded. That order
+ * is what makes the namespaces exact, at the price of one more round of
+ * downloads after the page's own -- it happens in parallel with nothing, so
+ * keep catalogs small (one per area) rather than one per language.
+ */ function withI18nPreload(resolve, options) {
+    const { locale: pickLocale, onLanguageSwitch = "declared", ...preload } = options;
+    let current;
+    return async (name, page)=>{
+        const component = await resolve(name, page);
+        const locale = page ? pickLocale(page) : undefined;
+        if (typeof locale === "string") {
+            const rendered = onLanguageSwitch === "rendered" && name === current ? renderedForSwitchTo(locale) : undefined;
+            if (rendered) demand.keepOnlyNamespaces([
+                createI18n.DEFAULT_NAMESPACE,
+                ...rendered
+            ]);
+            await preloadI18n(rendered ? {
+                ...preload,
+                locale,
+                declared: false,
+                namespaces: rendered
+            } : {
+                ...preload,
+                locale
+            });
+        }
+        // A new page starts a new record of what it renders with.
+        if (onLanguageSwitch === "rendered" && name !== current) demand.forgetRenderedNamespaces();
+        current = name;
+        return component;
+    };
+}
+/**
+ * What the page on screen has rendered with, when a live instance is about to
+ * change language; nothing (so the caller loads everything declared) when it
+ * is not a language switch or nothing has been recorded.
+ */ function renderedForSwitchTo(locale) {
+    const switching = demand.getLiveInstances().some((instance)=>instance.isInitialized && instance.language !== locale);
+    const rendered = demand.getRenderedNamespaces();
+    return switching && rendered.length > 0 ? rendered : undefined;
+}
 
 exports.LaravelBackend = createI18n.LaravelBackend;
-exports.LaravelFormat = createI18n.LaravelFormat;
 exports.createI18n = createI18n.createI18n;
 exports.documentLocale = createI18n.documentLocale;
+exports.laravelOptions = createI18n.laravelOptions;
+exports.registerCaseFormats = createI18n.registerCaseFormats;
 exports.syncDocumentLang = createI18n.syncDocumentLang;
+exports.declareNamespaces = demand.declareNamespaces;
+exports.preloadI18n = preloadI18n;
+exports.withI18nPreload = withI18nPreload;

package/dist/index.mjs

@@ -1,2 +1,125 @@
-export { L as LaravelBackend, a as LaravelFormat, c as createI18n, d as documentLocale, s as syncDocumentLang } from './shared/create-i18n-BSEwKsCX.mjs';
+import { t as toSources, r as recognizer, D as DEFAULT_NAMESPACE, a as resolver } from './shared/create-i18n-DaZzs1DJ.mjs';
+export { L as LaravelBackend, c as createI18n, d as documentLocale, l as laravelOptions, b as registerCaseFormats, s as syncDocumentLang } from './shared/create-i18n-DaZzs1DJ.mjs';
+import { g as getDeclaredNamespaces, d as declareNamespaces, a as getLiveInstances, k as keepOnlyNamespaces, f as forgetRenderedNamespaces, b as getRenderedNamespaces } from './shared/demand-6YnTqSM4.mjs';
 import 'i18next';
+
+function unique(values) {
+    return Array.from(new Set(values.filter((value)=>Boolean(value))));
+}
+/**
+ * The language and its base language: `es-MX` is looked up as `es-MX`, then `es`.
+ */ function languagesOf(locale, fallbackLocale) {
+    return unique([
+        locale,
+        locale.split(/[-_]/)[0],
+        fallbackLocale,
+        fallbackLocale === null || fallbackLocale === void 0 ? void 0 : fallbackLocale.split(/[-_]/)[0]
+    ]);
+}
+/**
+ * Load, before anything renders, the translations a page needs.
+ *
+ * With lazy files (the browser, or the server with `ssr: 'lazy'`) a namespace
+ * is a chunk to download, and rendering something that needs a chunk not yet
+ * there means waiting for it: the framework suspends and shows a fallback --
+ * a blank gap, where Inertia would have kept the old page on screen. Inertia
+ * avoids that by loading the next page's component before swapping to it.
+ * This does the same for its translations: call it (see `withI18nPreload()`)
+ * while the page is resolved, and by the time it renders every namespace it
+ * translates with is already in memory, so nothing suspends.
+ *
+ * It loads, for the language and its fallback, the namespaces declared by the
+ * modules evaluated so far -- the page component and everything it statically
+ * imports, which the Vite plugin records -- plus the ones given in
+ * `namespaces`. Loaded modules are cached, so calling it again costs nothing
+ * for what is already there. Live browser instances get the namespaces added,
+ * and the new language too when the page switched it.
+ *
+ * With eager files there is nothing to wait for and it returns at once.
+ */ async function preloadI18n({ files, locale, fallbackLocale, namespaces, declared = true }) {
+    if (!locale) return;
+    const sources = toSources(files);
+    const index = recognizer(sources);
+    const known = index.getAllNamespaces();
+    const wanted = namespaces === '*' ? known : unique([
+        DEFAULT_NAMESPACE,
+        ...declared ? getDeclaredNamespaces() : [],
+        ...namespaces !== null && namespaces !== void 0 ? namespaces : []
+    ]);
+    const needed = wanted.filter((namespace)=>known.includes(namespace));
+    const languages = languagesOf(locale, fallbackLocale);
+    // What a page needs, an instance created next (SSR) must start with too.
+    declareNamespaces(needed);
+    await Promise.all(languages.flatMap((language)=>needed.flatMap((namespace)=>resolver(sources, language, namespace))));
+    await Promise.all(getLiveInstances().map((instance)=>loadInto(instance, locale, needed)));
+}
+/**
+ * Give a running instance the namespaces (and the language) a page needs. The
+ * modules are cached by now, so its backend reads them without waiting.
+ */ async function loadInto(instance, locale, namespaces) {
+    if (!instance.isInitialized || namespaces.length === 0) return;
+    await instance.loadNamespaces(namespaces);
+    if (locale !== instance.language) {
+        const missing = namespaces.filter((namespace)=>!instance.hasResourceBundle(locale, namespace));
+        if (missing.length > 0) await instance.reloadResources(languagesOf(locale), missing);
+    }
+}
+/**
+ * Wrap a page resolver so a page never renders before its translations are in
+ * memory -- the same guarantee Inertia gives the page component itself, and
+ * for the same reason: nothing is swapped in until it can be shown whole.
+ *
+ * ```ts
+ * createInertiaApp({
+ *   resolve: withI18nPreload((name) => resolvePageComponent(...), {
+ *     files,
+ *     fallbackLocale: "en",
+ *     locale: (page) => page.props.locale as string,
+ *   }),
+ * });
+ * ```
+ *
+ * The page component is resolved first, which evaluates it and everything it
+ * imports and so declares their namespaces; then those are loaded. That order
+ * is what makes the namespaces exact, at the price of one more round of
+ * downloads after the page's own -- it happens in parallel with nothing, so
+ * keep catalogs small (one per area) rather than one per language.
+ */ function withI18nPreload(resolve, options) {
+    const { locale: pickLocale, onLanguageSwitch = "declared", ...preload } = options;
+    let current;
+    return async (name, page)=>{
+        const component = await resolve(name, page);
+        const locale = page ? pickLocale(page) : undefined;
+        if (typeof locale === "string") {
+            const rendered = onLanguageSwitch === "rendered" && name === current ? renderedForSwitchTo(locale) : undefined;
+            if (rendered) keepOnlyNamespaces([
+                DEFAULT_NAMESPACE,
+                ...rendered
+            ]);
+            await preloadI18n(rendered ? {
+                ...preload,
+                locale,
+                declared: false,
+                namespaces: rendered
+            } : {
+                ...preload,
+                locale
+            });
+        }
+        // A new page starts a new record of what it renders with.
+        if (onLanguageSwitch === "rendered" && name !== current) forgetRenderedNamespaces();
+        current = name;
+        return component;
+    };
+}
+/**
+ * What the page on screen has rendered with, when a live instance is about to
+ * change language; nothing (so the caller loads everything declared) when it
+ * is not a language switch or nothing has been recorded.
+ */ function renderedForSwitchTo(locale) {
+    const switching = getLiveInstances().some((instance)=>instance.isInitialized && instance.language !== locale);
+    const rendered = getRenderedNamespaces();
+    return switching && rendered.length > 0 ? rendered : undefined;
+}
+
+export { declareNamespaces, preloadI18n, withI18nPreload };

package/dist/react.cjs

@@ -3,17 +3,19 @@
 var jsxRuntime = require('react/jsx-runtime');
 var react = require('react');
 var reactI18next = require('react-i18next');
-var createI18n = require('./shared/create-i18n-WsDK4Z8L.cjs');
+var createI18n = require('./shared/create-i18n-DI7Eog6O.cjs');
 require('i18next');
+require('./shared/demand-sbjTXVnl.cjs');
 
 /**
  * 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 }) {
+ * While a lazy namespace that was not preloaded loads, the children suspend, which
+ * keeps server-rendered HTML in place until it can be hydrated. Preload them (see
+ * `withI18nPreload()`) and nothing ever suspends.
+ */ function LaravelReactI18nProvider({ children, files, locale, fallbackLocale, fallback = null }) {
     const [i18n] = react.useState(()=>createI18n.createI18n({
             files,
             locale,
@@ -31,7 +33,7 @@ require('i18next');
     return jsxRuntime.jsx(reactI18next.I18nextProvider, {
         i18n: i18n,
         children: jsxRuntime.jsx(react.Suspense, {
-            fallback: null,
+            fallback: fallback,
             children: children
         })
     });

package/dist/react.mjs

@@ -1,17 +1,19 @@
 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 { c as createI18n, s as syncDocumentLang } from './shared/create-i18n-DaZzs1DJ.mjs';
 import 'i18next';
+import './shared/demand-6YnTqSM4.mjs';
 
 /**
  * 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 }) {
+ * While a lazy namespace that was not preloaded loads, the children suspend, which
+ * keeps server-rendered HTML in place until it can be hydrated. Preload them (see
+ * `withI18nPreload()`) and nothing ever suspends.
+ */ function LaravelReactI18nProvider({ children, files, locale, fallbackLocale, fallback = null }) {
     const [i18n] = useState(()=>createI18n({
             files,
             locale,
@@ -29,7 +31,7 @@ import 'i18next';
     return jsx(I18nextProvider, {
         i18n: i18n,
         children: jsx(Suspense, {
-            fallback: null,
+            fallback: fallback,
             children: children
         })
     });