@i18n-micro/types 1.2.5 → 1.2.7

package/README.md

@@ -111,6 +111,21 @@ Represents global route configurations for different locales.
 
 Represents a key-value pair of translations.
 
+#### Page-level SEO head (`useI18nHead`)
+
+Types for per-page i18n SEO overrides: `I18nHeadInput`, `I18nHeadLink`, `I18nHeadMeta`, and `I18nHeadDisableGroup`. Use them in page helpers or when calling `useI18nHead` from `@i18n-micro/types` for typed `meta`, `link`, `replace`, and `disable` options.
+
+```typescript
+import type { I18nHeadInput } from '@i18n-micro/types'
+
+export function buildArticleHead(article: Article): I18nHeadInput {
+  return {
+    meta: [{ property: 'og:title', content: article.title }],
+    replace: { canonical: article.canonicalUrl, ogUrl: article.canonicalUrl },
+  }
+}
+```
+
 #### `Translation`
 
 Represents a translation value, which can be a string, number, boolean, nested translations, or `null`.

package/dist/index.d.cts

@@ -401,6 +401,47 @@ export interface ModuleOptions {
      * @default 0
      */
     cacheTtl?: number;
+    /**
+     * Named number formats per locale (Vue I18n-compatible).
+     * Enables `$tn(1000, 'currency')` style calls.
+     *
+     * @example
+     * numberFormats: {
+     *   en: { currency: { style: 'currency', currency: 'USD' } },
+     *   de: { currency: { style: 'currency', currency: 'EUR' } },
+     * }
+     */
+    numberFormats?: Record<string, Record<string, Intl.NumberFormatOptions>>;
+    /**
+     * Named datetime formats per locale (Vue I18n-compatible `datetimeFormats`).
+     * Enables `$td(date, 'short')` style calls.
+     *
+     * @example
+     * datetimeFormats: {
+     *   en: { short: { year: 'numeric', month: 'short', day: 'numeric' } },
+     *   de: { short: { year: 'numeric', month: 'short', day: 'numeric' } },
+     * }
+     */
+    datetimeFormats?: Record<string, Record<string, Intl.DateTimeFormatOptions>>;
+    /**
+     * HTTP `Cache-Control` max-age (seconds) for `/{apiBaseUrl}/:page/:locale/data.json`.
+     *
+     * Applies in full only while `dateBuild` busts the URL (`?v=...`), which is the default:
+     * the response is then `public, max-age=…, immutable` and safe for browsers and CDNs.
+     *
+     * - `dateBuild: 0`/`''` — the URL is stable, so this duration is *not* honoured; the
+     *   response becomes `public, max-age=0, must-revalidate` instead. A long `max-age` on an
+     *   unchanging URL pins the first payload a browser ever saw.
+     * - `0` — do not set `Cache-Control` at all (useful in local debugging)
+     * - Not applied in development (`import.meta.dev`) so HMR is not fought by the browser cache
+     * - Reaches only responses served through Nitro. Payloads copied into `public/` and served
+     *   by the hosting platform take that platform's headers — see the Performance guide.
+     *
+     * Analogous to `@nuxtjs/i18n` experimental `httpCacheDuration` (v10.2.0), but as an
+     * explicit response header rather than Nitro `defineCachedEventHandler` maxAge.
+     * @default 31536000
+     */
+    httpCacheDuration?: number;
     /**
      * Value used for cache-busting translation requests (`?v=...`).
      *
@@ -444,14 +485,14 @@ export interface TranslationPayloadOptions {
     /**
      * 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.
-     * @default true in `premerged` mode, `false` in `source` mode
+     * @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
+     * @default true in premerged mode, false in source mode
      */
     prerenderRoutes?: boolean;
     /**
@@ -533,5 +574,39 @@ export type Translation = CleanTranslation | unknown;
 export interface Translations {
     [key: string]: Translation;
 }
+/** Link entry for page-level i18n head overrides (`useI18nHead`). */
+export interface I18nHeadLink {
+    rel: string;
+    href: string;
+    hreflang?: string;
+    [key: string]: string | undefined;
+}
+/** Meta entry for page-level i18n head overrides (`useI18nHead`). */
+export interface I18nHeadMeta {
+    [key: string]: string | undefined;
+}
+/** Groups of built-in i18n SEO tags that can be disabled per page. */
+export type I18nHeadDisableGroup = 'hreflang' | 'x-default' | 'canonical' | 'og' | 'og-alternates' | 'html';
+/** Page-level overrides merged on top of `useLocaleHead` output. */
+export interface I18nHeadInput {
+    /** Extra or overriding `<html>` attributes. */
+    htmlAttrs?: Record<string, string>;
+    /** Meta tags appended after base i18n tags (deduped by `id` / `property` / `name`). */
+    meta?: I18nHeadMeta[];
+    /** Link tags appended after base i18n tags (deduped by `id` / `rel` + `hreflang`). */
+    link?: I18nHeadLink[];
+    /** Replace or remove specific built-in i18n SEO tags. */
+    replace?: {
+        canonical?: string | false;
+        hreflang?: I18nHeadLink[] | false;
+        xDefault?: I18nHeadLink | false;
+        ogLocale?: string | false;
+        ogUrl?: string | false;
+        /** Locale codes for `og:locale:alternate` (resolved via `locale.og` / `iso`). */
+        ogAlternates?: string[] | false;
+    };
+    /** Disable built-in i18n SEO tag groups for this page. */
+    disable?: I18nHeadDisableGroup[];
+}
 declare const init: () => void;
 export { init };

package/dist/index.d.ts

@@ -401,6 +401,47 @@ export interface ModuleOptions {
      * @default 0
      */
     cacheTtl?: number;
+    /**
+     * Named number formats per locale (Vue I18n-compatible).
+     * Enables `$tn(1000, 'currency')` style calls.
+     *
+     * @example
+     * numberFormats: {
+     *   en: { currency: { style: 'currency', currency: 'USD' } },
+     *   de: { currency: { style: 'currency', currency: 'EUR' } },
+     * }
+     */
+    numberFormats?: Record<string, Record<string, Intl.NumberFormatOptions>>;
+    /**
+     * Named datetime formats per locale (Vue I18n-compatible `datetimeFormats`).
+     * Enables `$td(date, 'short')` style calls.
+     *
+     * @example
+     * datetimeFormats: {
+     *   en: { short: { year: 'numeric', month: 'short', day: 'numeric' } },
+     *   de: { short: { year: 'numeric', month: 'short', day: 'numeric' } },
+     * }
+     */
+    datetimeFormats?: Record<string, Record<string, Intl.DateTimeFormatOptions>>;
+    /**
+     * HTTP `Cache-Control` max-age (seconds) for `/{apiBaseUrl}/:page/:locale/data.json`.
+     *
+     * Applies in full only while `dateBuild` busts the URL (`?v=...`), which is the default:
+     * the response is then `public, max-age=…, immutable` and safe for browsers and CDNs.
+     *
+     * - `dateBuild: 0`/`''` — the URL is stable, so this duration is *not* honoured; the
+     *   response becomes `public, max-age=0, must-revalidate` instead. A long `max-age` on an
+     *   unchanging URL pins the first payload a browser ever saw.
+     * - `0` — do not set `Cache-Control` at all (useful in local debugging)
+     * - Not applied in development (`import.meta.dev`) so HMR is not fought by the browser cache
+     * - Reaches only responses served through Nitro. Payloads copied into `public/` and served
+     *   by the hosting platform take that platform's headers — see the Performance guide.
+     *
+     * Analogous to `@nuxtjs/i18n` experimental `httpCacheDuration` (v10.2.0), but as an
+     * explicit response header rather than Nitro `defineCachedEventHandler` maxAge.
+     * @default 31536000
+     */
+    httpCacheDuration?: number;
     /**
      * Value used for cache-busting translation requests (`?v=...`).
      *
@@ -444,14 +485,14 @@ export interface TranslationPayloadOptions {
     /**
      * 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.
-     * @default true in `premerged` mode, `false` in `source` mode
+     * @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
+     * @default true in premerged mode, false in source mode
      */
     prerenderRoutes?: boolean;
     /**
@@ -533,5 +574,39 @@ export type Translation = CleanTranslation | unknown;
 export interface Translations {
     [key: string]: Translation;
 }
+/** Link entry for page-level i18n head overrides (`useI18nHead`). */
+export interface I18nHeadLink {
+    rel: string;
+    href: string;
+    hreflang?: string;
+    [key: string]: string | undefined;
+}
+/** Meta entry for page-level i18n head overrides (`useI18nHead`). */
+export interface I18nHeadMeta {
+    [key: string]: string | undefined;
+}
+/** Groups of built-in i18n SEO tags that can be disabled per page. */
+export type I18nHeadDisableGroup = 'hreflang' | 'x-default' | 'canonical' | 'og' | 'og-alternates' | 'html';
+/** Page-level overrides merged on top of `useLocaleHead` output. */
+export interface I18nHeadInput {
+    /** Extra or overriding `<html>` attributes. */
+    htmlAttrs?: Record<string, string>;
+    /** Meta tags appended after base i18n tags (deduped by `id` / `property` / `name`). */
+    meta?: I18nHeadMeta[];
+    /** Link tags appended after base i18n tags (deduped by `id` / `rel` + `hreflang`). */
+    link?: I18nHeadLink[];
+    /** Replace or remove specific built-in i18n SEO tags. */
+    replace?: {
+        canonical?: string | false;
+        hreflang?: I18nHeadLink[] | false;
+        xDefault?: I18nHeadLink | false;
+        ogLocale?: string | false;
+        ogUrl?: string | false;
+        /** Locale codes for `og:locale:alternate` (resolved via `locale.og` / `iso`). */
+        ogAlternates?: string[] | false;
+    };
+    /** Disable built-in i18n SEO tag groups for this page. */
+    disable?: I18nHeadDisableGroup[];
+}
 declare const init: () => void;
 export { init };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i18n-micro/types",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "TypeScript definitions for the Nuxt I18n Micro ecosystem.",
   "keywords": [
     "i18n",
@@ -51,14 +51,16 @@
   },
   "devDependencies": {
     "publint": "^0.3.17",
-    "vite": "^7.3.1",
-    "vite-plugin-dts": "^4.5.4"
+    "vite": "^7.3.6",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=18"
   },
   "scripts": {
     "build": "vite build",
-    "check:package": "publint"
+    "check:package": "publint",
+    "test": "vitest run --typecheck"
   }
 }