@genrwork/laravel-i18next 0.1.0 → 0.1.1

package/dist/svelte.mjs

@@ -1,7 +1,8 @@
 import { onDestroy, setContext, hasContext, getContext } from 'svelte';
 import { writable, derived } from 'svelte/store';
-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';
 
 const CONTEXT_KEY = 'laravel-i18next';
 /**
@@ -52,6 +53,11 @@ function getI18nextFromContext() {
     const instance = i18nextInstance !== null && i18nextInstance !== void 0 ? i18nextInstance : getI18nextFromContext();
     const revision = writable(0);
     const bump = ()=>revision.update((n)=>n + 1);
+    // Not preloaded (see `preloadI18n()`): load it now, `ready` turns true once it arrives.
+    const current = instance.language || instance.options.lng;
+    if (namespace && (!current || !instance.hasResourceBundle(current, namespace))) {
+        void instance.loadNamespaces(namespace);
+    }
     instance.on('languageChanged', bump);
     instance.on('loaded', bump);
     instance.on('added', bump);

package/dist/types/contrib/get-plural-index.d.ts

@@ -12,4 +12,4 @@
  * @param  {Number}  number
  * @return {Number}
  */
-export declare function getPluralIndex(locale: string, number: number): 1 | 0 | 3 | 2 | 4 | 5;
+export declare function getPluralIndex(locale: string, number: number): 1 | 0 | 2 | 3 | 4 | 5;

package/dist/types/defaults.d.ts

@@ -0,0 +1,18 @@
+import type { i18n, InitOptions } from 'i18next';
+/**
+ * The i18next options Laravel translations need. `createI18n()` applies them;
+ * pass them to `init()` yourself when you set i18next up by hand.
+ *
+ * - no key or namespace separator: Laravel keys are flat and contain dots
+ *   and colons (`auth.failed`, `Email:`);
+ * - an empty message counts as missing and falls back to the next language;
+ * - no escaping of interpolated values: React, Vue and Svelte already escape
+ *   what they render, and Laravel's `:name` replacements were never escaped.
+ */
+export declare const laravelOptions: InitOptions;
+/**
+ * Register the `uppercase`, `lowercase` and `capitalize` interpolation formats.
+ * The Vite plugin writes Laravel's `:NAME` as `{{name, uppercase}}` and `:Name`
+ * as `{{name, capitalize}}`; call this once the instance is initialized.
+ */
+export declare function registerCaseFormats(instance: i18n): void;

package/dist/types/demand.d.ts

@@ -0,0 +1,51 @@
+import type { i18n } from 'i18next';
+/**
+ * Namespaces the application's modules asked for, by evaluating.
+ *
+ * The Vite plugin adds one `declareNamespaces([...])` call to every module
+ * calling `useTranslation('ns')` (or `withTranslation`, `<Trans ns>`), so
+ * evaluating a module -- a page, a layout, any component it statically
+ * imports -- records which namespaces it will translate with. A bundler loads
+ * a page together with everything it imports, so by the time a page is
+ * resolved this set holds exactly the namespaces that page needs, however
+ * deeply they are nested, with nothing to declare by hand. `preloadI18n()`
+ * reads it.
+ *
+ * Only ever grows, and is shared by every i18next instance of the process.
+ *
+ * It lives on `globalThis`, under a registered symbol, and the code the Vite
+ * plugin injects writes to it directly instead of importing this module: a
+ * module can be evaluated before this one (a bundler is free to order a
+ * package's chunks around import cycles), can sit in a package that does not
+ * depend on this one, and a page bundle and a server bundle can each carry
+ * their own copy of this module -- none of that may lose a declaration.
+ */
+export declare const DECLARED_NAMESPACES_KEY = "laravel-i18next.declared";
+/**
+ * Record namespaces a module translates with. Called by the code the Vite
+ * plugin injects; call it yourself for a namespace requested dynamically
+ * (`useTranslation(name)`), which the plugin cannot see.
+ */
+export declare function declareNamespaces(namespaces: string | readonly string[]): void;
+export declare function getDeclaredNamespaces(): string[];
+/**
+ * Forget every declared namespace. For tests.
+ */
+export declare function clearDeclaredNamespaces(): void;
+export declare function trackInstance(instance: i18n): void;
+/**
+ * The namespaces the components of the live browser instances have rendered
+ * with since `forgetRenderedNamespaces()`, or none when nothing recorded them
+ * (another framework, or nothing has rendered yet).
+ */
+export declare function getRenderedNamespaces(): string[];
+export declare function forgetRenderedNamespaces(): void;
+/**
+ * Make the live instances load only these namespaces the next time their
+ * language changes. i18next remembers every namespace it ever loaded and
+ * loads them all again for a new language; this forgets the others, which a
+ * later `loadNamespaces()` (see `preloadI18n()`) brings back when a page
+ * asks for them.
+ */
+export declare function keepOnlyNamespaces(namespaces: readonly string[]): void;
+export declare function getLiveInstances(): i18n[];

package/dist/types/index.d.ts

@@ -1,7 +1,9 @@
 import LaravelBackend from './backend';
-import LaravelFormat from './format';
-export { LaravelBackend, LaravelFormat };
+export { LaravelBackend };
+export { laravelOptions, registerCaseFormats } from './defaults';
+export { declareNamespaces } from './demand';
+export { preloadI18n, withI18nPreload } from './preload';
+export type { PreloadOptions, ResolvedPage, WithI18nPreloadOptions } from './preload';
 export { createI18n, documentLocale, syncDocumentLang } from './shared/create-i18n';
 export type { LaravelI18nOptions } from './shared/create-i18n';
 export type { default as LaravelBackendOptions, LocaleFiles, LocaleFileSources } from './interfaces/options';
-export type { default as ReplacementsInterface } from './interfaces/replacements';

package/dist/types/plugin/convert.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Rewrite Laravel placeholders as i18next interpolations.
+ */
+export declare function toInterpolation(message: string): string;
+/**
+ * Convert one entry, returning the i18next entries it becomes (one for a
+ * plain message, several for a pluralized one). A list has its messages
+ * converted, anything else that is not a string is returned untouched.
+ */
+export declare function convertEntry(key: string, value: unknown, locale: string): Record<string, unknown>;

package/dist/types/plugin/namespaces.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Finds the i18next namespaces a module translates with, by reading its code.
+ * Deliberately a text scan and not a parse: it runs on every module of the
+ * app, on the code of any framework (JSX, Vue and Svelte output alike), and a
+ * namespace it over-reports is harmless -- `preloadI18n()` ignores names that
+ * have no language file.
+ *
+ * Recognized, with string literals only:
+ *
+ * - `useTranslation('auth')`, `useTranslation(['auth', 'teams'])`
+ *   (react-i18next, i18next-vue, and this package's Svelte `useTranslation`);
+ * - `withTranslation('auth')`;
+ * - `ns="auth"` / `ns={'auth'}` (`<Trans>`, `<Translation>`);
+ * - `{ ns: 'auth' }` (`t()` options, `getFixedT`).
+ *
+ * Comments are ignored, so documentation that quotes a call (this package's
+ * own, or commented-out code) declares nothing. A namespace requested through
+ * a variable is invisible to it: declare it with `declareNamespaces()`.
+ */
+export default function detectNamespaces(source: string): string[];

package/dist/types/plugin/parser.d.ts

@@ -6,6 +6,9 @@ export interface GeneratedFile {
  * Convert every `lang/{locale}/{namespace}.php` file into a sibling
  * `lang/{locale}/{namespace}.json` file, one per PHP file, so each PHP file
  * becomes its own i18next namespace instead of being merged with the others.
+ * The PHP file keeps Laravel's conventions (`:name` placeholders, `one|many`
+ * plural forms); the JSON is written the i18next way (`{{name}}`,
+ * `key_one` / `key_other`), see `src/plugin/convert.ts`.
  * A PHP file may sit at any depth under the locale directory --
  * `lang/{locale}/{ns1}/{ns2}.php` and deeper -- and gets its sibling `.json`
  * written at that same nested path; the resulting namespace name itself is

package/dist/types/plugin/sources.d.ts

@@ -2,9 +2,9 @@
  * One configured source, resolved against the project root.
  */
 export interface ResolvedSource {
-    /** As configured, e.g. `'Modules/*\/lang'`. */
+    /** As configured, e.g. `'packages/*\/lang'`. */
     pattern: string;
-    /** Root-relative glob for `import.meta.glob()`, e.g. `'/Modules/*\/lang/**\/*.json'`. */
+    /** Root-relative glob for `import.meta.glob()`, e.g. `'/packages/*\/lang/**\/*.json'`. */
     glob: string;
     /** Every directory the pattern currently expands to, existing ones only, sorted. */
     dirnames: string[];
@@ -13,7 +13,7 @@ export interface ResolvedSource {
  * Every directory an ordered source `pattern` currently expands to, relative
  * to `root`. A pattern with no `*` is a single literal directory (existing or
  * not -- callers decide what an absent literal directory means). A pattern
- * with exactly one `*` segment (e.g. `Modules/*\/lang`) is expanded against
+ * with exactly one `*` segment (e.g. `packages/*\/lang`) is expanded against
  * the filesystem: every existing subdirectory of the prefix before the `*`,
  * with the suffix after it appended, kept only when the full path also
  * exists, sorted. Two or more `*` segments throw -- unsupported.
@@ -28,8 +28,8 @@ export declare function expandDirs(pattern: string, root: string): string[];
  * so this is always root-relative (a leading `/`). A `*` segment in the
  * pattern passes through `path.resolve`/`path.relative`/`normalizePath`
  * completely untouched -- none of them treat it specially -- which is why
- * the emitted glob needs no separate wildcard handling: `Modules/*\/lang`
- * becomes `/Modules/*\/lang/**\/*.json` and `import.meta.glob()` expands the
+ * the emitted glob needs no separate wildcard handling: `packages/*\/lang`
+ * becomes `/packages/*\/lang/**\/*.json` and `import.meta.glob()` expands the
  * `*` itself, natively, at both dev and build time.
  *
  * @param pattern

package/dist/types/preload.d.ts

@@ -0,0 +1,99 @@
+import type { LocaleFileSources } from './interfaces/options';
+export interface PreloadOptions {
+    files: LocaleFileSources;
+    /**
+     * The language about to be shown.
+     */
+    locale: string;
+    /**
+     * Defaults to none; give the same value as the provider's `fallbackLocale`.
+     */
+    fallbackLocale?: string;
+    /**
+     * Namespaces to load besides the ones the evaluated modules declared (see
+     * `declareNamespaces()`), or `'*'` for every namespace there is.
+     */
+    namespaces?: string[] | '*';
+    /**
+     * Whether to also load every namespace the evaluated modules declared.
+     * Defaults to `true`; `false` loads only the default namespace and the
+     * ones in `namespaces`.
+     */
+    declared?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function preloadI18n({ files, locale, fallbackLocale, namespaces, declared }: PreloadOptions): Promise<void>;
+/**
+ * The page a resolver is asked for: Inertia calls `resolve(name, page)`, where
+ * `page.props` holds what the server shared.
+ */
+export interface ResolvedPage {
+    props?: object;
+}
+export interface WithI18nPreloadOptions<Page extends ResolvedPage = ResolvedPage> extends Omit<PreloadOptions, "locale"> {
+    /**
+     * The language a page is shown in: read it from whatever the server shares
+     * with every page, e.g. `(page) => page.props.locale`. A page it returns
+     * nothing for is resolved without loading translations.
+     */
+    locale: (page: Page) => string | undefined;
+    /**
+     * What to load when the page that is on screen is resolved again in another
+     * language (a language setting saved, a language chosen through a link).
+     *
+     * - `"declared"` (default): everything the evaluated modules declared, like
+     *   for any other page. Always safe.
+     * - `"rendered"`: only the namespaces that page has rendered with so far
+     *   (react-i18next records them), and i18next is told to load only those
+     *   too, instead of every namespace it ever loaded. A session that visited
+     *   many pages then downloads a few catalogs for the switch instead of all
+     *   of them; a namespace left out is loaded, before the page renders, when
+     *   a page that needs it is visited. Use it only when a page renders the
+     *   same namespaces in every language and nothing it opens later needs one
+     *   it has not shown yet, or that namespace suspends until it arrives.
+     *   Ignored, like when nothing was recorded, outside react-i18next.
+     */
+    onLanguageSwitch?: "declared" | "rendered";
+}
+/**
+ * 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.
+ */
+export declare function withI18nPreload<Component, Page extends ResolvedPage = ResolvedPage>(resolve: (name: string, page?: Page) => Component | Promise<Component>, options: WithI18nPreloadOptions<Page>): (name: string, page?: Page) => Promise<Component>;

package/dist/types/react/i18n-provider-props.d.ts

@@ -20,4 +20,9 @@ export default interface I18nProviderProps {
      * Defaults to the `<html lang="">` attribute, or `en`.
      */
     fallbackLocale?: string;
+    /**
+     * Shown while a namespace that was not preloaded (see `preloadI18n()`) loads.
+     * Defaults to nothing.
+     */
+    fallback?: ReactNode;
 }

package/dist/types/react/provider.d.ts

@@ -4,7 +4,8 @@ import type I18nProviderProps from './i18n-provider-props';
  *
  * 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.
+ * 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.
  */
-export default function LaravelReactI18nProvider({ children, files, locale, fallbackLocale }: I18nProviderProps): import("react").JSX.Element;
+export default function LaravelReactI18nProvider({ children, files, locale, fallbackLocale, fallback }: I18nProviderProps): import("react").JSX.Element;

package/dist/types/shared/create-i18n.d.ts

@@ -15,12 +15,18 @@ export declare function documentLocale(): string;
  */
 export declare function syncDocumentLang(instance: i18n): () => void;
 /**
- * Create an i18next instance translating Laravel language files: the default
+ * Create an i18next instance reading Laravel language files as i18next JSON: the default
  * namespace from `lang/{locale}.json`, and one namespace per `lang/{locale}/{namespace}.json`
- * file (generated by the Vite plugin, or hand-written).
+ * file (converted from PHP by the Vite plugin, or hand-written the i18next way).
  *
  * With eager files, every known namespace of the locale and fallback locale is
  * preloaded synchronously, so a first render never has to wait for translations.
- * With lazy files, namespaces are loaded on demand as components request them.
+ *
+ * With lazy files, only the namespaces the evaluated modules declared are loaded
+ * up front (see `declareNamespaces()`), plus the default one; any other is loaded
+ * when a component first asks for it, which suspends until it arrives. Loaded
+ * beforehand with `preloadI18n()` -- or `withI18nPreload()` around the page
+ * resolver -- the up front ones are already in memory, so the instance is ready
+ * synchronously and neither the first render nor a later page ever waits.
  */
 export declare function createI18n({ files, locale, fallbackLocale }: LaravelI18nOptions): i18n;

package/dist/types/utils/cache.d.ts

@@ -0,0 +1,3 @@
+import type LocaleFileInterface from '../interfaces/locale-file';
+export declare function getCachedModule(loader: object): LocaleFileInterface | undefined;
+export declare function setCachedModule(loader: object, module: LocaleFileInterface): void;

package/dist/types/vite.d.ts

@@ -5,11 +5,28 @@ export interface ConfigInterface {
      * hand-written `.json` files, `.php` files (each converted to a sibling
      * `.json`), or both -- but not both for the same namespace, since a
      * hand-written file is never overwritten (see `src/plugin/parser.ts`).
-     * One `*` segment is allowed per entry, e.g. `'Modules/*\/lang'`, expanded
+     * One `*` segment is allowed per entry, e.g. `'packages/*\/lang'`, expanded
      * against every matching directory that exists when the dev server starts
      * or a build runs. Defaults to `['lang']`.
      */
     sources?: string[];
+    /**
+     * How the server loads language files. `'eager'` (default) bundles them all
+     * into the server build, so SSR translates without any step of its own --
+     * simple, and right for a few languages and namespaces. `'lazy'` keeps each
+     * one a chunk of its own, loaded when a request needs it, so a project with
+     * many languages or namespaces keeps its server bundle (and startup) small;
+     * it needs `withI18nPreload()` around the page resolver, which loads a
+     * page's namespaces before it renders. The browser is always lazy.
+     */
+    ssr?: 'eager' | 'lazy';
+    /**
+     * Tell `preloadI18n()` which namespaces a page needs, by adding a
+     * `declareNamespaces([...])` call to every module that calls
+     * `useTranslation('ns')` and the like (see `src/plugin/namespaces.ts`).
+     * Defaults to `true`; turn it off to declare them yourself.
+     */
+    detectNamespaces?: boolean;
 }
 /**
  * Language files, one namespace per language file: loaded eagerly by server