@i18n-micro/astro 1.3.25 → 2.0.1

package/dist/router/types.d.ts

@@ -20,9 +20,10 @@ export interface I18nRoutingStrategy {
     };
     /**
      * Get route name from path (e.g., /en/about -> about)
-     * Used in middleware to set route name
+     * Used in middleware to set route name. `routePattern` is the page's pattern (`/blog/[slug]`), with
+     * a `[locale]` param already replaced by its value: use it to give every URL of a page one name.
      */
-    getRouteName?: (path: string, locales: string[]) => string;
+    getRouteName?: (path: string, locales: string[], routePattern?: string) => string;
     /**
      * Get locale from path
      * Checks if first segment is a locale code

package/dist/utils.d.cts

@@ -0,0 +1,112 @@
+import { ResolveTextOptions } from '@i18n-micro/core';
+import { CleanTranslation, Locale, Params, TranslationKey, Translations } from '@i18n-micro/types';
+import { LocaleHead } from '@i18n-micro/utils/locale-head';
+import { AstroGlobal } from 'astro';
+import { AstroI18n } from './composer.cjs';
+/** The subset of `AstroGlobal` the helpers read. */
+type Astro = Pick<AstroGlobal, 'locals' | 'url'> & Partial<Pick<AstroGlobal, 'params' | 'site'>>;
+/**
+ * Get i18n instance from Astro context
+ */
+export declare function getI18n(astro: Pick<AstroGlobal, 'locals'>): AstroI18n;
+/**
+ * Get current locale from Astro context
+ */
+export declare function getLocale(astro: Pick<AstroGlobal, 'locals'>): string;
+/**
+ * Get default locale from Astro context
+ */
+export declare function getDefaultLocale(astro: Pick<AstroGlobal, 'locals'>): string;
+/**
+ * Get all locales from Astro context
+ */
+export declare function getLocales(astro: Pick<AstroGlobal, 'locals'>): Locale[];
+/**
+ * Use i18n in Astro pages/components
+ * Returns helper functions for translations
+ */
+export declare function useI18n(astro: Astro): {
+    locale: string;
+    defaultLocale: string;
+    locales: Locale[];
+    t: (key: TranslationKey, params?: Params, defaultValue?: string | null, routeContext?: unknown) => CleanTranslation;
+    ts: (key: TranslationKey, params?: Params, defaultValue?: string, routeContext?: unknown) => string;
+    tc: (key: TranslationKey, count: number | Params, defaultValue?: string) => string;
+    tn: {
+        (value: number, options?: Intl.NumberFormatOptions): string;
+        (value: number, key: string, overrides?: Intl.NumberFormatOptions): string;
+        (value: number, key: string, locale: string, overrides?: Intl.NumberFormatOptions): string;
+    };
+    td: {
+        (value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
+        (value: Date | number | string, key: string, overrides?: Intl.DateTimeFormatOptions): string;
+        (value: Date | number | string, key: string, locale: string, overrides?: Intl.DateTimeFormatOptions): string;
+    };
+    tdr: (value: Date | number | string, options?: Intl.RelativeTimeFormatOptions) => string;
+    has: (key: TranslationKey, routeContext?: unknown) => boolean;
+    getRoute: () => string;
+    getRouteName: (path?: string) => string;
+    getLocaleFromPath: (path?: string) => string;
+    switchLocalePath: (newLocale: string) => string;
+    localizePath: (path: string, targetLocale?: string) => string;
+    getI18n: () => AstroI18n;
+    getBasePath: (url?: URL) => string;
+    addTranslations: (locale: string, translations: Translations, merge?: boolean) => void;
+    addRouteTranslations: (locale: string, routeName: string, translations: Translations, merge?: boolean) => void;
+    mergeTranslations: (locale: string, routeName: string, translations: Translations) => void;
+    clearCache: () => void;
+};
+/** What `<I18nSwitcher>` shows for a locale. A code is free-form: `constructor` must not read an inherited member. */
+export declare function localeLabel(locale: Locale, customLabels: Record<string, string>): string;
+/** `href` of an `<I18nLink>`: relative to the page, in `locale` (default the current one). */
+export declare function resolveLinkHref(astro: Astro, href: string, locale?: string): string;
+export interface I18nTProps extends ResolveTextOptions {
+    defaultValue?: string;
+}
+/** The text of an `<I18nT>`, `null` when `hideIfEmpty` hides it. With `html`, params arrive escaped; the translation is trusted. */
+export declare function resolveI18nT(astro: Astro, props: I18nTProps): string | null;
+/**
+ * Strip locale prefix from the current URL for `Astro.rewrite()` on `/[locale]/*` routes.
+ */
+export declare function getLocaleRewritePath(astro: Astro): string;
+/**
+ * Validate `:locale`, sync i18n/locals, and return the base path for `Astro.rewrite()`.
+ * Returns a `Response` when the locale param is invalid.
+ */
+export declare function prepareLocaleRewrite(astro: Astro & Pick<AstroGlobal, 'params'>): Response | string;
+/**
+ * Generate locale head meta tags for SEO
+ */
+export interface LocaleHeadOptions {
+    /** Origin of the absolute URLs. Default: `site` from the Astro config, else root-relative URLs. */
+    baseUrl?: string;
+    addDirAttribute?: boolean;
+    addSeoAttributes?: boolean;
+    /**
+     * Also emit bare-language `hreflang` tags derived from `iso` (never from routing `code`).
+     * @default false
+     */
+    hreflangBaseLanguage?: boolean;
+}
+export type LocaleHeadResult = LocaleHead;
+export declare function useLocaleHead(astro: Astro, options?: LocaleHeadOptions): LocaleHeadResult;
+/**
+ * Props to pass to client islands (Vue, React, Svelte, Preact)
+ */
+export interface I18nClientProps {
+    locale: string;
+    /** The tag plurals go by: the locale's `iso` when it has one. */
+    pluralLocale?: string;
+    /** Tags of the codes that have one, for `setLocale`. Absent when there are none. */
+    localeIso?: Record<string, string>;
+    fallbackLocale: string;
+    translations: Record<string, Translations>;
+    currentRoute: string;
+}
+/**
+ * Props for a client island: what `t()` can answer on this page (route, root and fallback keys),
+ * or only `keys` of that, which is the way to keep the page small. Stored trees are shared, an
+ * island must not write into them.
+ */
+export declare function getI18nProps(astro: Pick<AstroGlobal, 'locals'>, keys?: string[]): I18nClientProps;
+export {};

package/dist/utils.d.ts

@@ -1,32 +1,36 @@
+import { ResolveTextOptions } from '@i18n-micro/core';
 import { CleanTranslation, Locale, Params, TranslationKey, Translations } from '@i18n-micro/types';
+import { LocaleHead } from '@i18n-micro/utils/locale-head';
 import { AstroGlobal } from 'astro';
-import { AstroI18n } from './composer';
+import { AstroI18n } from './composer.js';
+/** The subset of `AstroGlobal` the helpers read. */
+type Astro = Pick<AstroGlobal, 'locals' | 'url'> & Partial<Pick<AstroGlobal, 'params' | 'site'>>;
 /**
  * Get i18n instance from Astro context
  */
-export declare function getI18n(astro: AstroGlobal): AstroI18n;
+export declare function getI18n(astro: Pick<AstroGlobal, 'locals'>): AstroI18n;
 /**
  * Get current locale from Astro context
  */
-export declare function getLocale(astro: AstroGlobal): string;
+export declare function getLocale(astro: Pick<AstroGlobal, 'locals'>): string;
 /**
  * Get default locale from Astro context
  */
-export declare function getDefaultLocale(astro: AstroGlobal): string;
+export declare function getDefaultLocale(astro: Pick<AstroGlobal, 'locals'>): string;
 /**
  * Get all locales from Astro context
  */
-export declare function getLocales(astro: AstroGlobal): Locale[];
+export declare function getLocales(astro: Pick<AstroGlobal, 'locals'>): Locale[];
 /**
  * Use i18n in Astro pages/components
  * Returns helper functions for translations
  */
-export declare function useI18n(astro: AstroGlobal): {
+export declare function useI18n(astro: Astro): {
     locale: string;
     defaultLocale: string;
     locales: Locale[];
-    t: (key: TranslationKey, params?: Params, defaultValue?: string | null, routeName?: string) => CleanTranslation;
-    ts: (key: TranslationKey, params?: Params, defaultValue?: string, routeName?: string) => string;
+    t: (key: TranslationKey, params?: Params, defaultValue?: string | null, routeContext?: unknown) => CleanTranslation;
+    ts: (key: TranslationKey, params?: Params, defaultValue?: string, routeContext?: unknown) => string;
     tc: (key: TranslationKey, count: number | Params, defaultValue?: string) => string;
     tn: {
         (value: number, options?: Intl.NumberFormatOptions): string;
@@ -39,7 +43,7 @@ export declare function useI18n(astro: AstroGlobal): {
         (value: Date | number | string, key: string, locale: string, overrides?: Intl.DateTimeFormatOptions): string;
     };
     tdr: (value: Date | number | string, options?: Intl.RelativeTimeFormatOptions) => string;
-    has: (key: TranslationKey, routeName?: string) => boolean;
+    has: (key: TranslationKey, routeContext?: unknown) => boolean;
     getRoute: () => string;
     getRouteName: (path?: string) => string;
     getLocaleFromPath: (path?: string) => string;
@@ -47,24 +51,34 @@ export declare function useI18n(astro: AstroGlobal): {
     localizePath: (path: string, targetLocale?: string) => string;
     getI18n: () => AstroI18n;
     getBasePath: (url?: URL) => string;
-    addTranslations: (locale: string, translations: Record<string, unknown>, merge?: boolean) => void;
-    addRouteTranslations: (locale: string, routeName: string, translations: Record<string, unknown>, merge?: boolean) => void;
-    mergeTranslations: (locale: string, routeName: string, translations: Record<string, unknown>) => void;
+    addTranslations: (locale: string, translations: Translations, merge?: boolean) => void;
+    addRouteTranslations: (locale: string, routeName: string, translations: Translations, merge?: boolean) => void;
+    mergeTranslations: (locale: string, routeName: string, translations: Translations) => void;
     clearCache: () => void;
 };
+/** What `<I18nSwitcher>` shows for a locale. A code is free-form: `constructor` must not read an inherited member. */
+export declare function localeLabel(locale: Locale, customLabels: Record<string, string>): string;
+/** `href` of an `<I18nLink>`: relative to the page, in `locale` (default the current one). */
+export declare function resolveLinkHref(astro: Astro, href: string, locale?: string): string;
+export interface I18nTProps extends ResolveTextOptions {
+    defaultValue?: string;
+}
+/** The text of an `<I18nT>`, `null` when `hideIfEmpty` hides it. With `html`, params arrive escaped; the translation is trusted. */
+export declare function resolveI18nT(astro: Astro, props: I18nTProps): string | null;
 /**
  * Strip locale prefix from the current URL for `Astro.rewrite()` on `/[locale]/*` routes.
  */
-export declare function getLocaleRewritePath(astro: AstroGlobal): string;
+export declare function getLocaleRewritePath(astro: Astro): string;
 /**
  * Validate `:locale`, sync i18n/locals, and return the base path for `Astro.rewrite()`.
  * Returns a `Response` when the locale param is invalid.
  */
-export declare function prepareLocaleRewrite(astro: AstroGlobal): Response | string;
+export declare function prepareLocaleRewrite(astro: Astro & Pick<AstroGlobal, 'params'>): Response | string;
 /**
  * Generate locale head meta tags for SEO
  */
 export interface LocaleHeadOptions {
+    /** Origin of the absolute URLs. Default: `site` from the Astro config, else root-relative URLs. */
     baseUrl?: string;
     addDirAttribute?: boolean;
     addSeoAttributes?: boolean;
@@ -74,35 +88,25 @@ export interface LocaleHeadOptions {
      */
     hreflangBaseLanguage?: boolean;
 }
-export interface LocaleHeadResult {
-    htmlAttrs: {
-        lang?: string;
-        dir?: 'ltr' | 'rtl' | 'auto';
-    };
-    link: Array<{
-        rel: string;
-        href: string;
-        hreflang?: string;
-    }>;
-    meta: Array<{
-        property: string;
-        content: string;
-    }>;
-}
-export declare function useLocaleHead(astro: AstroGlobal, options?: LocaleHeadOptions): LocaleHeadResult;
+export type LocaleHeadResult = LocaleHead;
+export declare function useLocaleHead(astro: Astro, options?: LocaleHeadOptions): LocaleHeadResult;
 /**
  * Props to pass to client islands (Vue, React, Svelte, Preact)
  */
 export interface I18nClientProps {
     locale: string;
+    /** The tag plurals go by: the locale's `iso` when it has one. */
+    pluralLocale?: string;
+    /** Tags of the codes that have one, for `setLocale`. Absent when there are none. */
+    localeIso?: Record<string, string>;
     fallbackLocale: string;
     translations: Record<string, Translations>;
     currentRoute: string;
 }
 /**
- * Prepares props to pass to a client island.
- * Accepts a list of keys to pass to the island.
- * Uses i18n methods for proper routesLocaleLinks support.
- * currentRoute is already normalized via middleware (getRouteName), so we use it directly.
+ * Props for a client island: what `t()` can answer on this page (route, root and fallback keys),
+ * or only `keys` of that, which is the way to keep the page small. Stored trees are shared, an
+ * island must not write into them.
  */
-export declare function getI18nProps(astro: AstroGlobal, keys?: string[]): I18nClientProps;
+export declare function getI18nProps(astro: Pick<AstroGlobal, 'locals'>, keys?: string[]): I18nClientProps;
+export {};

package/dist/virtual.d.ts

@@ -0,0 +1,21 @@
+declare module 'virtual:i18n-micro/config' {
+  export const config: {
+    defaultLocale: string
+    fallbackLocale: string
+    locales: import('@i18n-micro/types').Locale[]
+    localeCodes: string[]
+    translationDir: string | null
+    autoDetect: boolean
+    redirectToDefault: boolean
+    localeCookie: string | null
+    missingWarn: boolean
+    base: string
+  }
+}
+
+declare module 'virtual:i18n-micro/messages' {
+  export const messages: {
+    root: Record<string, import('@i18n-micro/types').Translations>
+    routes: Record<string, Record<string, import('@i18n-micro/types').Translations>>
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i18n-micro/astro",
-  "version": "1.3.25",
+  "version": "2.0.1",
   "description": "Astro integration for i18n-micro — translations, routing, and islands.",
   "keywords": [
     "astro",
@@ -13,6 +13,11 @@
     "url": "https://github.com/s00d/nuxt-i18n-micro/issues"
   },
   "license": "MIT",
+  "author": {
+    "name": "s00d",
+    "email": "Virus191288@gmail.com",
+    "url": "https://s00d.github.io/"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/s00d/nuxt-i18n-micro.git",
@@ -40,6 +45,14 @@
       },
       "default": "./dist/index.mjs"
     },
+    "./middleware": {
+      "types": "./dist/auto-middleware.d.ts",
+      "import": "./dist/middleware.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    },
     "./env": {
       "types": "./dist/env.d.ts"
     },
@@ -80,28 +93,28 @@
     "access": "public"
   },
   "dependencies": {
-    "@i18n-micro/core": "^1.3.22",
-    "@i18n-micro/node": "^1.2.21",
-    "@i18n-micro/types": "^1.2.18",
-    "@i18n-micro/utils": "^1.0.27"
+    "@i18n-micro/core": "^2.0.1",
+    "@i18n-micro/types": "^2.0.1",
+    "@i18n-micro/runtime": "^2.0.1",
+    "@i18n-micro/utils": "^2.0.1"
   },
   "devDependencies": {
     "astro": "^5.0.0 || ^6.0.0 || ^7.0.0",
-    "preact": "^10.27.2 || ^11.0.0-0",
-    "publint": "^0.3.24",
-    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+    "preact": "^10.0.0 || ^11.0.0",
+    "publint": "^0.3.25",
+    "react": "^18.0.0 || ^19.0.0",
     "svelte": "^4.0.0 || ^5.0.0",
-    "vite": "^8.3.1",
-    "vite-plugin-dts": "^5.1.1",
-    "vitest": "^5.0.2",
-    "vue": "^3.5.43"
+    "vite": "^8.3.5",
+    "vite-plugin-dts": "^5.1.2",
+    "vitest": "^5.1.0",
+    "vue": "^3.5.44"
   },
   "peerDependencies": {
     "astro": "^5.0.0 || ^6.0.0 || ^7.0.0",
-    "preact": "^10.27.2 || ^11.0.0-0",
+    "preact": "^10.0.0 || ^11.0.0",
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "svelte": "^4.0.0 || ^5.0.0",
-    "vue": "^3.5.43"
+    "vue": "^3.3.0"
   },
   "peerDependenciesMeta": {
     "svelte": {
@@ -118,7 +131,7 @@
     }
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "vite build",

package/src/auto-middleware.ts

@@ -0,0 +1,26 @@
+/** `@i18n-micro/astro/middleware`: what `i18nIntegration` installs. Nothing here reads the disk, so it runs on the edge too. */
+import { config } from 'virtual:i18n-micro/config'
+import { messages } from 'virtual:i18n-micro/messages'
+import { localeIsoMap } from '@i18n-micro/core'
+import { AstroI18n } from './composer'
+import { createI18nMiddleware } from './middleware'
+
+const i18n = new AstroI18n({
+  locale: config.defaultLocale,
+  fallbackLocale: config.fallbackLocale,
+  missingWarn: config.missingWarn,
+  localeIso: localeIsoMap(config.locales),
+  messages: messages.root,
+  routeMessages: messages.routes,
+})
+
+export const onRequest = createI18nMiddleware({
+  i18n,
+  defaultLocale: config.defaultLocale,
+  locales: config.localeCodes,
+  localeObjects: config.locales,
+  autoDetect: config.autoDetect,
+  redirectToDefault: config.redirectToDefault,
+  localeCookie: config.localeCookie,
+  base: config.base,
+})

package/src/client/core.ts

@@ -1,52 +1,37 @@
-import { interpolate } from '@i18n-micro/core'
-import type { Params, Translations } from '@i18n-micro/types'
+import { convertible, defaultPlural, FormatService, interpolate, ownValue, resolveTranslation, textOf } from '@i18n-micro/core'
+import type { CleanTranslation, Getter, Params, TranslationKey, Translations } from '@i18n-micro/types'
+import type { I18nClientProps } from '../utils'
 
 /**
  * I18n state for client islands
  */
 export interface I18nState {
   locale: string
+  /** The tag plurals go by, when it is not `locale`. */
+  pluralLocale?: string
+  /** Tags of the codes that have one: `setLocale` finds the new locale's here. */
+  localeIso?: Record<string, string>
   fallbackLocale: string
   translations: Record<string, Translations> // routeName -> translations
   currentRoute: string
 }
 
-// Helper function to find a translation in a Translations object
-// Returns the value as-is, including objects (for nested translations)
-function findTranslation<T = unknown>(translations: Translations | null, key: string): T | null {
-  if (translations === null || typeof key !== 'string') {
-    return null
-  }
+type Value = string | number | boolean | Translations
 
-  let value: string | number | boolean | Translations | unknown | null = translations
-
-  // Direct key access
-  if (translations[key]) {
-    value = translations[key]
-  } else {
-    // Search by nested keys (e.g. "nested.message")
-    const parts = key.toString().split('.')
-    for (const part of parts) {
-      if (value && typeof value === 'object' && value !== null && part in value) {
-        value = (value as Translations)[part]
-      } else {
-        return null
-      }
-    }
-  }
-
-  // Return value as-is (can be string, number, boolean, object, or null)
-  // This matches CleanTranslation type which allows objects
-  return (value as T) ?? null
+/**
+ * The value at `key` in the route's dictionary, or null. Own keys only (core's `resolveTranslation`):
+ * `toString` or `__proto__` is a missing key, not `Object.prototype`'s.
+ */
+function lookup(state: I18nState, key: string, routeName?: string): Value | null {
+  const route = routeName || state.currentRoute
+  const translations = Object.prototype.hasOwnProperty.call(state.translations, route) ? state.translations[route] : undefined
+  return (resolveTranslation(translations, key) as Value | null) ?? null
 }
 
 /**
- * Pure function to get a translation from state
- *
- * Note: This is a simplified version optimized for client-side islands.
- * It supports basic translation lookup and interpolation.
- * Returns CleanTranslation which can be string, number, boolean, object, or null.
- * For advanced features like Linked Messages (@:path.to.key), use the server-side i18n instance.
+ * Pure function to get a translation from state, answering as the server's `t()` does over the
+ * same keys. `getI18nProps` already merged the root and fallback dictionaries into the state.
+ * For Linked Messages (@:path.to.key), use the server-side i18n instance.
  */
 export function translate(
   state: I18nState,
@@ -55,41 +40,121 @@ export function translate(
   defaultValue?: string | null,
   routeName?: string,
 ): string | number | boolean | Translations | null {
-  if (!key) {
-    return defaultValue || key || ''
+  if (!key) return ''
+  // `??`: 0, false and '' are values, as on the server
+  const value = lookup(state, key, routeName) ?? (defaultValue || key)
+  if (typeof value === 'object') return convertible(value)
+  return typeof value === 'string' && params ? interpolate(value, params) : value
+}
+
+/**
+ * `tc` of every island adapter, as the server's `BaseI18n.tc`: a missing key gives `defaultValue`
+ * (else the key), because the getter reports the miss to `defaultPlural` instead of the key.
+ */
+export function translatePlural(state: I18nState, key: TranslationKey, count: number | Params, defaultValue?: string): string {
+  const { count: countValue, ...params } = typeof count === 'number' ? { count } : count
+  if (countValue === undefined || countValue === null) return defaultValue ?? key
+  const getter: Getter = (k, p, dv) => {
+    const raw = lookup(state, k)
+    if (raw === null) return dv === undefined ? undefined : dv || k
+    return p && typeof raw === 'string' ? interpolate(raw, p) : raw
   }
+  return defaultPlural(key, Number(countValue), params, state.pluralLocale ?? state.locale, getter) ?? defaultValue ?? key
+}
 
-  const route = routeName || state.currentRoute
-  let value: string | number | boolean | Translations | null = null
+/**
+ * Checks if a translation exists in the state: a subtree counts, as on the server
+ */
+export function hasTranslation(state: I18nState, key: string, routeName?: string): boolean {
+  return lookup(state, key, routeName) !== null
+}
 
-  if (state.translations[route]) {
-    value = findTranslation<string | number | boolean | Translations>(state.translations[route], key)
-  }
+/** `state` in another locale, with that locale's plural tag. */
+export const withLocale = (state: I18nState, locale: string): I18nState => ({
+  ...state,
+  locale,
+  pluralLocale: state.localeIso && (ownValue(state.localeIso, locale) as string | undefined),
+})
 
-  // If not found, use defaultValue or key
-  if (!value) {
-    value = defaultValue === undefined ? key : defaultValue || key
-  }
+const formatter = /*#__PURE__*/ new FormatService()
 
-  if (typeof value === 'string' && params) {
-    return interpolate(value, params)
+const isoTag = (state: I18nState): string => state.pluralLocale ?? state.locale
+
+/** What every island adapter returns, over the state it reads at each call. */
+export function createIslandApi(getState: () => I18nState) {
+  const t = (key: TranslationKey, params?: Params, defaultValue?: string | null, routeName?: string): CleanTranslation =>
+    translate(getState(), key as string, params, defaultValue, routeName)
+
+  return {
+    t,
+    ts: (key: TranslationKey, params?: Params, defaultValue?: string, routeName?: string): string =>
+      textOf(t(key, params, defaultValue, routeName)) ?? defaultValue ?? (key as string),
+    tc: (key: TranslationKey, count: number | Params, defaultValue?: string): string => translatePlural(getState(), key, count, defaultValue),
+    tn: (value: number, options?: Intl.NumberFormatOptions): string => formatter.formatNumber(value, isoTag(getState()), options),
+    td: (value: Date | number | string, options?: Intl.DateTimeFormatOptions): string => formatter.formatDate(value, isoTag(getState()), options),
+    tdr: (value: Date | number | string, options?: Intl.RelativeTimeFormatOptions): string =>
+      formatter.formatRelativeTime(value, isoTag(getState()), options),
+    has: (key: TranslationKey, routeName?: string): boolean => hasTranslation(getState(), key as string, routeName),
+    getRoute: (): string => getState().currentRoute,
   }
-  return value
 }
 
-/**
- * Checks if a translation exists in the state
- */
-export function hasTranslation(state: I18nState, key: string, routeName?: string): boolean {
-  const route = routeName || state.currentRoute
-  const routeTranslations = state.translations[route]
+type SetI18nState = (update: I18nState | ((current: I18nState) => I18nState)) => void
+
+export interface I18nContextValue {
+  state: I18nState
+  setState: SetI18nState
+}
+
+/** What an island binding needs of its library: core stays free of framework imports. */
+interface IslandLibrary<Children, Element, Context extends { Provider: unknown }> {
+  createContext: (value: I18nContextValue | null) => Context
+  createElement: (type: Context['Provider'], props: { value: I18nContextValue }, children: Children) => Element
+  useCallback: <T extends (arg: string) => void>(callback: T, deps: unknown[]) => T
+  useContext: (context: Context) => I18nContextValue | null
+  useMemo: <T>(factory: () => T, deps: unknown[]) => T
+  useState: <T>(initial: T) => [T, (update: T | ((current: T) => T)) => void]
+}
+
+/** The provider and hook of an island library (Preact and React have one API). */
+export function createIslandBinding<Children, Element, Context extends { Provider: unknown }>(lib: IslandLibrary<Children, Element, Context>) {
+  const { createContext, createElement, useCallback, useContext, useMemo, useState } = lib
+  const I18nContext = createContext(null)
+
+  /** A new `value` (an island with `transition:persist`) replaces the state. */
+  function I18nProvider({ children, value }: { children: Children; value: I18nClientProps }): Element {
+    const [state, setState] = useState<I18nState>(value)
+    const [seen, setSeen] = useState(value)
+    if (seen !== value) {
+      setSeen(value)
+      setState(value)
+    }
+    const context = useMemo(() => ({ state, setState }), [state])
+    return createElement(I18nContext.Provider, { value: context }, children)
+  }
+
+  function useAstroI18n() {
+    const context = useContext(I18nContext)
+    if (!context) {
+      throw new Error('useAstroI18n must be used within an I18nProvider')
+    }
+    const { state, setState } = context
+    const api = useMemo(() => createIslandApi(() => state), [state])
+    const setLocale = useCallback((locale: string) => setState((current) => withLocale(current, locale)), [setState])
+    const setRoute = useCallback((currentRoute: string) => setState((current) => ({ ...current, currentRoute })), [setState])
+
+    return {
+      ...api,
+
+      // Locale state
+      locale: state.locale,
+      fallbackLocale: state.fallbackLocale,
+      currentRoute: state.currentRoute,
 
-  if (routeTranslations) {
-    const value = findTranslation(routeTranslations, key)
-    if (value !== null && typeof value !== 'object') {
-      return true
+      setLocale,
+      setRoute,
     }
   }
 
-  return false
+  return { I18nProvider, useAstroI18n }
 }

package/src/client/index.ts

@@ -1,13 +1,4 @@
-// Core utilities (pure functions)
-
+// The pure core. Framework adapters live in their own entries (`./client/vue`, `./client/react`,
+// `./client/preact`, `./client/svelte`): each needs its framework installed, and an island needs one.
 export type { I18nState } from './core'
 export { hasTranslation, translate } from './core'
-// Preact adapter
-export { I18nProvider as I18nProviderPreact, useAstroI18n as useAstroI18nPreact } from './preact'
-
-// React adapter
-export { I18nProvider, useAstroI18n as useAstroI18nReact } from './react'
-// Svelte adapter
-export { createI18nStore, useAstroI18n as useAstroI18nSvelte } from './svelte'
-// Vue adapter
-export { provideI18n, useAstroI18n as useAstroI18nVue } from './vue'