@i18n-micro/types 1.2.7 → 1.2.10

package/dist/index.d.cts

@@ -162,10 +162,10 @@ export interface ModuleOptions {
     strategy?: Strategies;
     /**
      * Base URL for SEO meta tags (canonical, og:url, hreflang).
-     * - `undefined` — dynamically resolved from the current request URL
+     * - A concrete URL string (e.g. `'https://example.com'`) — used as-is (highest priority).
+     * - `undefined` — falls back to `site.url` from `nuxt-site-config` when that module is
+     *   present, otherwise the current request origin
      *   (`useRequestURL().origin` on server, `window.location.origin` on client).
-     *   Best for multi-domain deployments.
-     * - A concrete URL string (e.g. `'https://example.com'`) — used as-is.
      * @default undefined
      */
     metaBaseUrl?: string;
@@ -183,6 +183,13 @@ export interface ModuleOptions {
      * @default true
      */
     metaTrustForwardedProto?: boolean;
+    /**
+     * Also emit a bare-language `hreflang` derived from each locale's `iso`
+     * (e.g. `es-ES` → also `es`). The first regional locale in `locales` claims
+     * the bare tag for that language. Routing `code` is never used — only `iso || code`.
+     * @default false
+     */
+    hreflangBaseLanguage?: boolean;
     /**
      * Register the `defineI18nRoute()` macro plugin, enabling per-page `defineI18nRoute()` calls.
      * @default true
@@ -251,11 +258,13 @@ export interface ModuleOptions {
      */
     translationDir?: string;
     /**
-     * Controls how pre-merged translation payload files are emitted during build.
+     * Controls how translation payloads are emitted (Node: `public/<apiBaseUrl>`; Edge: Nitro `serverAssets`).
+     *
+     * - **Node**: `serverAssets` means local SSR via `readFile` under `public/` (no Rollup `raw:`).
+     * - **Edge**: `serverAssets` registers Nitro `serverAssets` (`assets:i18n`); it does not force a public copy.
      *
-     * Keep the defaults for the existing all-in-one behavior. For serverless or CDN-backed
-     * deployments, disable individual outputs to avoid duplicating large locale payloads in
-     * both Nitro server assets and public assets.
+     * Keep the defaults for the usual all-in-one setup. For large Edge catalogs prefer `mode: 'source'`.
+     * For CDN-backed deployments, disable local outputs and set `apiBaseClientHost` / `apiBaseServerHost`.
      */
     translationPayloads?: TranslationPayloadOptions;
     /**
@@ -265,9 +274,14 @@ export interface ModuleOptions {
      */
     autoDetectLanguage?: boolean;
     /**
-     * URL path on which automatic language detection and redirect occur.
-     * - `'/'` — detect only on the root path.
-     * - `'*'` — detect and redirect on every path (including locale-prefixed ones).
+     * Where cookie / Accept-Language preference redirects may run (when `redirects` is enabled).
+     * - `'/'` — only `/` (deep links in the default locale stay reachable; default)
+     * - `'no_prefix'` — only paths without a locale prefix
+     * - `'*'` — every path, including rewriting an explicit locale prefix
+     *   (e.g. `/fr/about` → `/de/about` when the cookie prefers `de`)
+     * - any other string — exact path match (e.g. `'/welcome'`)
+     *
+     * Prefixed strategy cleanup (e.g. `/en` → `/` under `prefix_except_default`) is not gated.
      * @default '/'
      */
     autoDetectPath?: string;
@@ -292,13 +306,17 @@ export interface ModuleOptions {
         [key: string]: string;
     };
     /**
-     * Custom pluralization function or a path to a file exporting one.
-     * When a string path is provided, the file is imported at build time.
-     * The function receives `(key, count, params, locale, getter)` and should return
-     * the correct plural form as a string, or `null` to fall back to the built-in logic.
-     * @default built-in pluralization (singular/plural by count)
+     * Custom pluralization function.
+     * Receives `(key, count, params, locale, getter)` and should return the selected
+     * plural form as a string, or `null`/`undefined` to fall back to the built-in
+     * `defaultPlural` logic (so you can override only some locales).
+     *
+     * For the Nuxt module the function is serialized with `.toString()` into
+     * `.nuxt/i18n.plural.mjs` — it must be self-contained (no imports / outer scope).
+     * A file path string is **not** supported.
+     * @default built-in pluralization (form index by count)
      */
-    plural?: string | PluralFunc;
+    plural?: PluralFunc;
     /**
      * Disable per-page translation files.
      * When `true`, only global translations (`{locale}.json`) are loaded;
@@ -462,17 +480,19 @@ export interface ModuleOptions {
 export interface TranslationPayloadOptions {
     /**
      * Translation payload strategy.
-     * - `premerged`: build-time page/locale matrix (default)
-     * - `source`: compact source files merged at runtime (recommended for large serverless apps)
+     * - `premerged`: build-time `{page}/{locale}/data.json` matrix (default)
+     * - `source`: compact source files merged at runtime (prefer on Edge / large catalogs)
      * @default 'premerged'
      */
     mode?: 'premerged' | 'source';
     /**
-     * Register translation payload files as Nitro server assets.
-     * In `premerged` mode this is the fully merged page/locale matrix.
-     * In `source` mode this is the compact layer-merged source directory.
-     * Required for the built-in local `_locales` server route unless translations are fetched
-     * from `apiBaseServerHost`.
+     * Local SSR payloads: Node reads `public/<apiBaseUrl>` (forces public copy); Edge embeds via Nitro `serverAssets`.
+     *
+     * - **Node**: no Nitro `serverAssets` (avoids Rollup `raw:`). SSR reads
+     *   `public/<apiBaseUrl|publicDir>` as `{page}/{locale}/data.json`; when this is `true`,
+     *   a public copy is forced even if `publicAssets` is false.
+     * - **Edge** (`nitro.node === false`): Nitro `serverAssets` (`assets:i18n`) with the same
+     *   layout as `mode`. Does **not** force a public copy — set `publicAssets: true` for CDN.
      * @default true
      */
     serverAssets?: boolean;
@@ -483,21 +503,21 @@ export interface TranslationPayloadOptions {
      */
     serverHandler?: boolean;
     /**
-     * Copy translation payload files into Nitro public assets during production builds.
-     * In `source` mode this copies the compact source directory, not a pre-merged matrix.
+     * Copy payloads into Nitro public output. Premerged → `{page}/{locale}/data.json` under `apiBaseUrl`; source → compact tree.
+     *
+     * On Node this tree is also the SSR source when `serverAssets` forces a public copy.
      * @default true in premerged mode, false in source mode
      */
     publicAssets?: boolean;
     /**
-     * Add translation data routes to Nuxt/Nitro prerender output.
-     * Disable this when `_locales` payloads are served from an external host/CDN or should not be
-     * materialized into public output.
-     * @default true in premerged mode, false in source mode
+     * Opt in to Nitro-prerender `/{apiBaseUrl}/.../data.json`. Usually redundant when premerged `publicAssets` already wrote those files.
+     * @default false
      */
     prerenderRoutes?: boolean;
     /**
-     * Public output directory for copied translation payloads, relative to Nitro's public directory.
-     * Defaults to `translationDir`.
+     * Public output folder relative to Nitro public root. Defaults to `apiBaseUrl` (`_locales`).
+     *
+     * So static files match client fetch URLs (`/{apiBaseUrl}/{page}/{locale}/data.json`).
      */
     publicDir?: string;
     /**
@@ -558,6 +578,15 @@ export interface ModulePrivateOptionsExtend extends ModuleOptions {
     };
     /** Preload index translations in Nitro global middleware. */
     serverTranslationPreload?: boolean;
+    /**
+     * Absolute buildDir path to payload files (`.nuxt/i18n-merged` or `.nuxt/i18n-source`).
+     * Used by the Node fs reader in `import.meta.dev` / `import.meta.prerender`.
+     */
+    payloadFsDir: string;
+    /**
+     * Directory under Nitro `public/` for prod payload files (defaults to `translationDir`).
+     */
+    payloadPublicRel: string;
 }
 /** Object shape for a translation value that contains singular/plural forms. */
 export interface PluralTranslations {

package/dist/index.d.ts

@@ -162,10 +162,10 @@ export interface ModuleOptions {
     strategy?: Strategies;
     /**
      * Base URL for SEO meta tags (canonical, og:url, hreflang).
-     * - `undefined` — dynamically resolved from the current request URL
+     * - A concrete URL string (e.g. `'https://example.com'`) — used as-is (highest priority).
+     * - `undefined` — falls back to `site.url` from `nuxt-site-config` when that module is
+     *   present, otherwise the current request origin
      *   (`useRequestURL().origin` on server, `window.location.origin` on client).
-     *   Best for multi-domain deployments.
-     * - A concrete URL string (e.g. `'https://example.com'`) — used as-is.
      * @default undefined
      */
     metaBaseUrl?: string;
@@ -183,6 +183,13 @@ export interface ModuleOptions {
      * @default true
      */
     metaTrustForwardedProto?: boolean;
+    /**
+     * Also emit a bare-language `hreflang` derived from each locale's `iso`
+     * (e.g. `es-ES` → also `es`). The first regional locale in `locales` claims
+     * the bare tag for that language. Routing `code` is never used — only `iso || code`.
+     * @default false
+     */
+    hreflangBaseLanguage?: boolean;
     /**
      * Register the `defineI18nRoute()` macro plugin, enabling per-page `defineI18nRoute()` calls.
      * @default true
@@ -251,11 +258,13 @@ export interface ModuleOptions {
      */
     translationDir?: string;
     /**
-     * Controls how pre-merged translation payload files are emitted during build.
+     * Controls how translation payloads are emitted (Node: `public/<apiBaseUrl>`; Edge: Nitro `serverAssets`).
+     *
+     * - **Node**: `serverAssets` means local SSR via `readFile` under `public/` (no Rollup `raw:`).
+     * - **Edge**: `serverAssets` registers Nitro `serverAssets` (`assets:i18n`); it does not force a public copy.
      *
-     * Keep the defaults for the existing all-in-one behavior. For serverless or CDN-backed
-     * deployments, disable individual outputs to avoid duplicating large locale payloads in
-     * both Nitro server assets and public assets.
+     * Keep the defaults for the usual all-in-one setup. For large Edge catalogs prefer `mode: 'source'`.
+     * For CDN-backed deployments, disable local outputs and set `apiBaseClientHost` / `apiBaseServerHost`.
      */
     translationPayloads?: TranslationPayloadOptions;
     /**
@@ -265,9 +274,14 @@ export interface ModuleOptions {
      */
     autoDetectLanguage?: boolean;
     /**
-     * URL path on which automatic language detection and redirect occur.
-     * - `'/'` — detect only on the root path.
-     * - `'*'` — detect and redirect on every path (including locale-prefixed ones).
+     * Where cookie / Accept-Language preference redirects may run (when `redirects` is enabled).
+     * - `'/'` — only `/` (deep links in the default locale stay reachable; default)
+     * - `'no_prefix'` — only paths without a locale prefix
+     * - `'*'` — every path, including rewriting an explicit locale prefix
+     *   (e.g. `/fr/about` → `/de/about` when the cookie prefers `de`)
+     * - any other string — exact path match (e.g. `'/welcome'`)
+     *
+     * Prefixed strategy cleanup (e.g. `/en` → `/` under `prefix_except_default`) is not gated.
      * @default '/'
      */
     autoDetectPath?: string;
@@ -292,13 +306,17 @@ export interface ModuleOptions {
         [key: string]: string;
     };
     /**
-     * Custom pluralization function or a path to a file exporting one.
-     * When a string path is provided, the file is imported at build time.
-     * The function receives `(key, count, params, locale, getter)` and should return
-     * the correct plural form as a string, or `null` to fall back to the built-in logic.
-     * @default built-in pluralization (singular/plural by count)
+     * Custom pluralization function.
+     * Receives `(key, count, params, locale, getter)` and should return the selected
+     * plural form as a string, or `null`/`undefined` to fall back to the built-in
+     * `defaultPlural` logic (so you can override only some locales).
+     *
+     * For the Nuxt module the function is serialized with `.toString()` into
+     * `.nuxt/i18n.plural.mjs` — it must be self-contained (no imports / outer scope).
+     * A file path string is **not** supported.
+     * @default built-in pluralization (form index by count)
      */
-    plural?: string | PluralFunc;
+    plural?: PluralFunc;
     /**
      * Disable per-page translation files.
      * When `true`, only global translations (`{locale}.json`) are loaded;
@@ -462,17 +480,19 @@ export interface ModuleOptions {
 export interface TranslationPayloadOptions {
     /**
      * Translation payload strategy.
-     * - `premerged`: build-time page/locale matrix (default)
-     * - `source`: compact source files merged at runtime (recommended for large serverless apps)
+     * - `premerged`: build-time `{page}/{locale}/data.json` matrix (default)
+     * - `source`: compact source files merged at runtime (prefer on Edge / large catalogs)
      * @default 'premerged'
      */
     mode?: 'premerged' | 'source';
     /**
-     * Register translation payload files as Nitro server assets.
-     * In `premerged` mode this is the fully merged page/locale matrix.
-     * In `source` mode this is the compact layer-merged source directory.
-     * Required for the built-in local `_locales` server route unless translations are fetched
-     * from `apiBaseServerHost`.
+     * Local SSR payloads: Node reads `public/<apiBaseUrl>` (forces public copy); Edge embeds via Nitro `serverAssets`.
+     *
+     * - **Node**: no Nitro `serverAssets` (avoids Rollup `raw:`). SSR reads
+     *   `public/<apiBaseUrl|publicDir>` as `{page}/{locale}/data.json`; when this is `true`,
+     *   a public copy is forced even if `publicAssets` is false.
+     * - **Edge** (`nitro.node === false`): Nitro `serverAssets` (`assets:i18n`) with the same
+     *   layout as `mode`. Does **not** force a public copy — set `publicAssets: true` for CDN.
      * @default true
      */
     serverAssets?: boolean;
@@ -483,21 +503,21 @@ export interface TranslationPayloadOptions {
      */
     serverHandler?: boolean;
     /**
-     * Copy translation payload files into Nitro public assets during production builds.
-     * In `source` mode this copies the compact source directory, not a pre-merged matrix.
+     * Copy payloads into Nitro public output. Premerged → `{page}/{locale}/data.json` under `apiBaseUrl`; source → compact tree.
+     *
+     * On Node this tree is also the SSR source when `serverAssets` forces a public copy.
      * @default true in premerged mode, false in source mode
      */
     publicAssets?: boolean;
     /**
-     * Add translation data routes to Nuxt/Nitro prerender output.
-     * Disable this when `_locales` payloads are served from an external host/CDN or should not be
-     * materialized into public output.
-     * @default true in premerged mode, false in source mode
+     * Opt in to Nitro-prerender `/{apiBaseUrl}/.../data.json`. Usually redundant when premerged `publicAssets` already wrote those files.
+     * @default false
      */
     prerenderRoutes?: boolean;
     /**
-     * Public output directory for copied translation payloads, relative to Nitro's public directory.
-     * Defaults to `translationDir`.
+     * Public output folder relative to Nitro public root. Defaults to `apiBaseUrl` (`_locales`).
+     *
+     * So static files match client fetch URLs (`/{apiBaseUrl}/{page}/{locale}/data.json`).
      */
     publicDir?: string;
     /**
@@ -558,6 +578,15 @@ export interface ModulePrivateOptionsExtend extends ModuleOptions {
     };
     /** Preload index translations in Nitro global middleware. */
     serverTranslationPreload?: boolean;
+    /**
+     * Absolute buildDir path to payload files (`.nuxt/i18n-merged` or `.nuxt/i18n-source`).
+     * Used by the Node fs reader in `import.meta.dev` / `import.meta.prerender`.
+     */
+    payloadFsDir: string;
+    /**
+     * Directory under Nitro `public/` for prod payload files (defaults to `translationDir`).
+     */
+    payloadPublicRel: string;
 }
 /** Object shape for a translation value that contains singular/plural forms. */
 export interface PluralTranslations {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i18n-micro/types",
-  "version": "1.2.7",
+  "version": "1.2.10",
   "description": "TypeScript definitions for the Nuxt I18n Micro ecosystem.",
   "keywords": [
     "i18n",