@i18n-micro/astro 1.3.24 → 2.0.0

package/src/integration.ts

@@ -1,78 +1,132 @@
-import type { Locale, ModuleOptions, PluralFunc } from '@i18n-micro/types'
-import type { AstroIntegration, HookParameters } from 'astro'
+import type { Locale } from '@i18n-micro/types'
+import { getEnabledLocaleCodes } from '@i18n-micro/utils/active-locales'
+import { forwardSlashes } from '@i18n-micro/utils/app-path'
+import type { AstroConfig, AstroIntegration, HookParameters } from 'astro'
+import type { FSWatcher } from 'vite'
 import { AstroI18n, type AstroI18nOptions } from './composer'
-import { setGlobalRoutingStrategy } from './routing-context'
-import type { I18nRoutingStrategy } from './router/types'
 
-export interface I18nIntegrationOptions extends Omit<ModuleOptions, 'plural'> {
+export interface I18nIntegrationOptions {
   locale: string
   fallbackLocale?: string
   locales?: Locale[]
-  messages?: Record<string, Record<string, unknown>>
-  plural?: PluralFunc
   missingWarn?: boolean
-  missingHandler?: (locale: string, key: string, routeName: string) => void
   localeCookie?: string | null
   autoDetect?: boolean
+  /** `/` also redirects when nothing prefers another locale: see `createI18nMiddleware`. */
   redirectToDefault?: boolean
+  /** Bundled into the server at build time, relative to the project root. */
   translationDir?: string
-  routingStrategy?: I18nRoutingStrategy
+  /** Page files (`pages/about/de.json`) count as root translations. */
+  disablePageLocales?: boolean
+  /**
+   * `false`: no middleware from the integration. Write `src/middleware.ts` with `createI18nMiddleware`
+   * for what cannot cross from the Astro config to the server bundle: `plural`, `missingHandler`, a strategy.
+   */
+  middleware?: boolean
 }
 
-export { getGlobalRoutingStrategy, runWithRoutingStrategy, setGlobalRoutingStrategy } from './routing-context'
+/** Options that moved to the server bundle: passing one here would silently lose it. */
+const MOVED_OPTIONS = ['messages', 'plural', 'missingHandler', 'routingStrategy']
+
+const CONFIG_MODULE = 'virtual:i18n-micro/config'
+const MESSAGES_MODULE = 'virtual:i18n-micro/messages'
+const hidden = (id: string) => `\0${id}`
+/** Not a literal, so a server bundle of this entry never sees `node:fs`: only the config process comes here. */
+const NODE_ENTRY = '@i18n-micro/astro/node'
+
+type ConfigSetup = HookParameters<'astro:config:setup'>
+
+/** What crosses from the Astro config process to the server bundle: only serializable values. */
+function publishedConfig(options: I18nIntegrationOptions, base: string) {
+  const locales = options.locales || []
+  return {
+    defaultLocale: options.locale,
+    fallbackLocale: options.fallbackLocale || options.locale,
+    locales,
+    localeCodes: getEnabledLocaleCodes(locales),
+    translationDir: options.translationDir || null,
+    autoDetect: options.autoDetect ?? true,
+    redirectToDefault: options.redirectToDefault ?? false,
+    localeCookie: options.localeCookie === null ? null : options.localeCookie || 'i18n-locale',
+    missingWarn: options.missingWarn ?? false,
+    base: base === '/' ? '' : base,
+  }
+}
 
 /**
- * Astro Integration for i18n-micro
+ * The two virtual modules. The dictionaries become code at build time, so the server reads no disk
+ * and an edge runtime works. Their files are watched: in dev an edit reloads the module.
  */
-export function i18nIntegration(options: I18nIntegrationOptions): AstroIntegration {
-  const { locale: defaultLocale, fallbackLocale, translationDir, routingStrategy } = options
+function i18nVitePlugin(options: I18nIntegrationOptions, config: AstroConfig) {
+  const code = `export const config = ${JSON.stringify(publishedConfig(options, config.base))}`
 
-  setGlobalRoutingStrategy(routingStrategy || null)
+  let watched: string[] = []
+
+  const loadMessages = async (watch: (file: string) => void) => {
+    const { translationDir, disablePageLocales } = options
+    if (!translationDir) return 'export const messages = {"root":{},"routes":{}}'
+    const { readTranslationDir } = (await import(/* @vite-ignore */ NODE_ENTRY)) as typeof import('./node')
+    const { messages, files } = readTranslationDir({ translationDir, rootDir: config.root, disablePageLocales })
+    watched = files
+    for (const file of files) watch(file)
+    return `export const messages = ${JSON.stringify(messages)}`
+  }
+
+  return {
+    name: 'vite-plugin-i18n-micro-config',
+    resolveId(id: string) {
+      return id === CONFIG_MODULE || id === MESSAGES_MODULE ? hidden(id) : undefined
+    },
+    load(this: { addWatchFile(file: string): void }, id: string) {
+      if (id === hidden(CONFIG_MODULE)) return code
+      return id === hidden(MESSAGES_MODULE) ? loadMessages((file) => this.addWatchFile(file)) : undefined
+    },
+    configureServer(server: { watcher: FSWatcher }) {
+      const dir = options.translationDir && `/${options.translationDir.replace(/^\.?\/+|\/+$/g, '')}/`
+      if (!dir) return
+      // A file Vite knows reloads by itself; a new one has no module yet: a change of a known file does it.
+      const reload = (file: string) => {
+        const isLocaleFile = file.endsWith('.json') && forwardSlashes(file).includes(dir)
+        if (isLocaleFile && watched[0]) server.watcher.emit('change', watched[0])
+      }
+      server.watcher.on('add', reload)
+    },
+  }
+}
+
+/**
+ * `Astro.currentLocale` and `astro:i18n` know the locales, the routing stays ours. Only with a
+ * `src/middleware.ts`: Astro rejects `routing: 'manual'` when the only middleware is an integration's
+ * (`MissingMiddlewareForInternationalization`), and any other routing would fight this one.
+ */
+function astroI18nConfig(options: I18nIntegrationOptions, config: AstroConfig) {
+  const locales = getEnabledLocaleCodes(options.locales)
+  if (options.middleware !== false || config.i18n || !locales.includes(options.locale)) return {}
+  return { i18n: { locales, defaultLocale: options.locale, routing: 'manual' as const } }
+}
+
+/** Astro integration for i18n-micro: publishes the config and dictionaries, and installs the middleware. */
+export function i18nIntegration(options: I18nIntegrationOptions): AstroIntegration {
+  const moved = MOVED_OPTIONS.find((key) => (options as unknown as Record<string, unknown>)[key] !== undefined)
+  if (moved)
+    throw new Error(`[i18n-micro] i18nIntegration no longer takes "${moved}": pass it to createI18n / createI18nMiddleware in src/middleware.ts`)
 
   return {
     name: '@i18n-micro/astro',
     hooks: {
-      // 1. Vite setup (virtual module) happens here
       'astro:config:setup': (params) => {
-        const { updateConfig } = params as HookParameters<'astro:config:setup'>
-
-        const virtualModuleId = 'virtual:i18n-micro/config'
-        const resolvedVirtualModuleId = `\0${virtualModuleId}`
-
-        const configData = {
-          defaultLocale,
-          fallbackLocale: fallbackLocale || defaultLocale,
-          locales: options.locales || [],
-          localeCodes: (options.locales || []).map((l) => l.code),
-          translationDir: translationDir || null,
-          autoDetect: options.autoDetect ?? true,
-          redirectToDefault: options.redirectToDefault ?? false,
-          localeCookie: options.localeCookie === null ? null : options.localeCookie || 'i18n-locale',
-          missingWarn: options.missingWarn ?? false,
-        }
-
+        const { updateConfig, addMiddleware, config } = params as ConfigSetup
         updateConfig({
+          ...astroI18nConfig(options, config),
           vite: {
-            plugins: [
-              {
-                name: 'vite-plugin-i18n-micro-config',
-                resolveId(id) {
-                  if (id === virtualModuleId) {
-                    return resolvedVirtualModuleId
-                  }
-                },
-                load(id) {
-                  if (id === resolvedVirtualModuleId) {
-                    return `export const config = ${JSON.stringify(configData)}`
-                  }
-                },
-              },
-            ],
+            // the middleware and the components import virtual modules and `.astro` files: Vite has to process them
+            ssr: { noExternal: ['@i18n-micro/astro'] },
+            plugins: [i18nVitePlugin(options, config)],
           },
         })
+        if (options.middleware !== false) addMiddleware({ order: 'pre', entrypoint: '@i18n-micro/astro/middleware' })
       },
 
-      // 2. Type injection happens here (per Astro documentation)
       'astro:config:done': (params) => {
         const { injectTypes } = params as HookParameters<'astro:config:done'>
 
@@ -91,7 +145,15 @@ export function i18nIntegration(options: I18nIntegrationOptions): AstroIntegrati
                 autoDetect: boolean;
                 redirectToDefault: boolean;
                 localeCookie: string | null;
-                missingWarn: boolean | 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>>;
               }
             }
           `,
@@ -100,9 +162,8 @@ export function i18nIntegration(options: I18nIntegrationOptions): AstroIntegrati
     },
   }
 }
-/**
- * Create i18n instance (for manual setup)
- */
+
+/** Create an i18n instance (for a `src/middleware.ts` of your own). */
 export function createI18n(options: AstroI18nOptions): AstroI18n {
   return new AstroI18n(options)
 }

package/src/middleware.ts

@@ -1,8 +1,22 @@
 import type { Locale } from '@i18n-micro/types'
-import { detectLocaleFromAcceptLanguage } from '@i18n-micro/utils/accept-language'
+import { getEnabledLocaleCodes } from '@i18n-micro/utils/active-locales'
+import { DEFAULT_COOKIE_MAX_AGE } from '@i18n-micro/utils/cookie'
+import { resolveLocale } from '@i18n-micro/utils/resolve-locale'
 import type { MiddlewareHandler } from 'astro'
 import type { AstroI18n } from './composer'
-import { getGlobalRoutingStrategy, runWithRoutingStrategy } from './routing-context'
+import {
+  asksForPage,
+  header,
+  isPageView,
+  isSwitch,
+  localeOfPath,
+  normalizeBase,
+  resolveRequest,
+  withBase,
+  type I18nRequest,
+  type I18nRouting,
+} from './request'
+import { createAstroRouterAdapter } from './router/adapter'
 import type { I18nRoutingStrategy } from './router/types'
 // Import shim to ensure App.Locals is available
 import './env.d'
@@ -12,106 +26,77 @@ export interface I18nMiddlewareOptions {
   defaultLocale: string
   locales: string[]
   localeObjects?: Locale[]
+  /** `/` redirects to the locale the cookie / Accept-Language prefer (default `true`); pages keep the URL's locale. */
   autoDetect?: boolean
+  /**
+   * `/` also redirects when nothing prefers another locale: to the home `routingStrategy` resolves
+   * for the default locale (default `false`). Without one `/` stays: it is the default locale's page.
+   */
   redirectToDefault?: boolean
   routingStrategy?: I18nRoutingStrategy
+  /** Cookie holding the visitor's locale (default `'i18n-locale'`); `null` disables it. */
+  localeCookie?: string | null
+  /** Astro's `base`, `config.base` of the virtual config. */
+  base?: string
 }
 
-/**
- * Create Astro middleware for i18n locale detection
- */
-export function createI18nMiddleware(options: I18nMiddlewareOptions): MiddlewareHandler {
-  const {
-    i18n: globalI18n, // This is the global singleton with cache
-    defaultLocale,
-    locales,
-    localeObjects,
-    autoDetect: _autoDetect = true,
-    redirectToDefault: _redirectToDefault = false,
-    routingStrategy,
-  } = options
-
-  // Get routing strategy from options or global context
-  const strategy = routingStrategy || getGlobalRoutingStrategy()
-
-  return async (context, next) => {
-    // FIX: If locale is already preserved in locals (e.g. during Astro.rewrite),
-    // skip redetection to prevent overwriting with default locale.
-    if (context.locals.locale && context.locals.i18n) {
-      return next()
-    }
-
-    const url = context.url
-    const pathname = url.pathname
-
-    // If no routing strategy, use basic fallback
-    if (!strategy) {
-      // Basic fallback: just set route name from path
-      const requestI18n = globalI18n.clone(defaultLocale)
-      const routeName = pathname === '/' || pathname === '' ? 'index' : pathname.split('/').filter(Boolean).join('-')
-      requestI18n.setRoute(routeName)
+export const DEFAULT_ASTRO_LOCALE_COOKIE = 'i18n-locale'
 
-      // @ts-ignore private property mismatch between src and dist types
-      context.locals.i18n = requestI18n
-      context.locals.locale = defaultLocale
-      context.locals.defaultLocale = defaultLocale
-      context.locals.locales = localeObjects || locales.map((code) => ({ code }))
-      context.locals.currentUrl = url
-
-      return next()
-    }
-
-    // Create context-aware routing strategy with current URL
-    const contextStrategy: I18nRoutingStrategy = {
-      ...strategy,
-      getCurrentPath: () => pathname,
-      getRoute: () => ({
-        fullPath: url.pathname + url.search,
-        query: Object.fromEntries(url.searchParams),
-      }),
-    }
-
-    // 1. Check if locale is in path
-    const pathSegments = pathname.split('/').filter(Boolean)
-    const firstSegment = pathSegments[0]
-    const hasLocalePrefix = firstSegment !== undefined && locales.includes(firstSegment)
-
-    // 2. Determine locale
-    let detectedLocale: string
-
-    if (hasLocalePrefix && firstSegment) {
-      detectedLocale = firstSegment
-    } else {
-      // Use routing strategy if available, otherwise fallback
-      if (contextStrategy.getLocaleFromPath) {
-        detectedLocale = contextStrategy.getLocaleFromPath(pathname, defaultLocale, locales)
-      } else {
-        detectedLocale = defaultLocale
-      }
-    }
+interface CookieReader {
+  get: (name: string) => { value: string } | undefined
+}
 
-    // 3. Create per-request instance sharing the cache
-    const requestI18n = globalI18n.clone(detectedLocale)
+function cookie(cookies: CookieReader, name: string | null): string | null {
+  if (name === null) return null
+  try {
+    return cookies.get(name)?.value ?? null
+  } catch {
+    return null
+  }
+}
 
-    // 4. Set route name using routing strategy
-    const routeName = contextStrategy.getRouteName ? contextStrategy.getRouteName(pathname, locales) : 'index'
-    requestI18n.setRoute(routeName)
+/**
+ * Every path method a strategy leaves out comes from the default adapter. The strategy's own stay
+ * bound to it: a class with methods on its prototype or `#private` fields works.
+ */
+function completeStrategy(strategy: I18nRoutingStrategy | null | undefined, locales: Locale[], defaultLocale: string): I18nRoutingStrategy {
+  const fallback = createAstroRouterAdapter(locales, defaultLocale)
+  if (!strategy) return fallback
+  const source = strategy as unknown as Record<string, unknown>
+  const complete: Record<string, unknown> = {}
+  for (const [name, method] of Object.entries(fallback)) {
+    const own = source[name]
+    complete[name] = typeof own === 'function' ? own.bind(strategy) : method
+  }
+  return complete as unknown as I18nRoutingStrategy
+}
 
-    // 5. Store in locals (Type-safe now thanks to astro-shim.d.ts)
-    // @ts-ignore private property mismatch between src and dist types
-    context.locals.i18n = requestI18n
-    context.locals.locale = detectedLocale
-    context.locals.defaultLocale = defaultLocale
-    context.locals.locales = localeObjects || locales.map((code) => ({ code }))
-    context.locals.currentUrl = url
-    context.locals.routingStrategy = contextStrategy
+interface PreferenceInput {
+  cookies: CookieReader
+  headers: Headers
+  localeCookie: string | null
+  autoDetect: boolean
+}
 
-    return runWithRoutingStrategy(contextStrategy, () => next())
-  }
+/** Precedence of a visitor's preference over a routing that is already complete. */
+function preferredLocale(
+  pathname: string,
+  routing: Omit<I18nRouting, 'base'>,
+  { cookies, headers, localeCookie, autoDetect }: PreferenceInput,
+): string {
+  return resolveLocale({
+    defaultLocale: routing.defaultLocale,
+    validLocales: routing.locales,
+    autoDetectLanguage: autoDetect,
+    url: localeOfPath(pathname, routing),
+    cookie: autoDetect ? cookie(cookies, localeCookie) : null,
+    acceptLanguage: autoDetect ? header({ request: { headers } }, 'accept-language') : null,
+  })
 }
 
 /**
- * Detect locale from request
+ * Locale a visitor prefers: URL prefix → cookie → Accept-Language → default, the one precedence of
+ * `resolveLocale`. An explicit prefix always wins; `autoDetect: false` leaves only the URL.
  */
 export function detectLocale(
   pathname: string,
@@ -119,44 +104,113 @@ export function detectLocale(
   headers: Headers,
   defaultLocale: string,
   locales: string[],
-  localeCookie: string | null = 'i18n-locale',
+  localeCookie: string | null = DEFAULT_ASTRO_LOCALE_COOKIE,
   routingStrategy?: I18nRoutingStrategy | null,
+  autoDetect = true,
 ): string {
-  const strategy = routingStrategy ?? getGlobalRoutingStrategy()
-
-  // 1. Try path
-  let locale = defaultLocale
-  if (strategy?.getLocaleFromPath) {
-    locale = strategy.getLocaleFromPath(pathname, defaultLocale, locales)
-  } else {
-    // Fallback: check if first segment is a locale
-    const segments = pathname.split('/').filter(Boolean)
-    const firstSegment = segments[0]
-    if (firstSegment && locales.includes(firstSegment)) {
-      locale = firstSegment
-    }
+  const strategy = completeStrategy(
+    routingStrategy,
+    locales.map((code) => ({ code })),
+    defaultLocale,
+  )
+  return preferredLocale(pathname, { defaultLocale, locales, strategy }, { cookies, headers, localeCookie, autoDetect })
+}
+
+let warnedTwice = false
+
+/** Two middlewares made by this function: the first wins, the second one's options would be lost silently. */
+function warnTwice(): void {
+  if (warnedTwice) return
+  warnedTwice = true
+  console.warn('[i18n-micro] i18nIntegration already installs the middleware: pass `middleware: false` to it to use your own createI18nMiddleware.')
+}
+
+/** Create Astro middleware for i18n locale detection */
+export function createI18nMiddleware(options: I18nMiddlewareOptions): MiddlewareHandler {
+  const { i18n: globalI18n, defaultLocale, localeObjects, autoDetect = true } = options
+  const localeCookie = options.localeCookie === undefined ? DEFAULT_ASTRO_LOCALE_COOKIE : options.localeCookie
+  const allLocales = localeObjects ?? options.locales.map((code) => ({ code }))
+  const base = normalizeBase(options.base)
+  const routing: I18nRouting = {
+    defaultLocale,
+    base,
+    locales: getEnabledLocaleCodes(allLocales).filter((code) => options.locales.includes(code)),
+    strategy: completeStrategy(options.routingStrategy, allLocales, defaultLocale),
   }
+  const cookieOptions = { path: base || '/', maxAge: DEFAULT_COOKIE_MAX_AGE, sameSite: 'lax' as const }
+  const varyOn = localeCookie === null ? 'Accept-Language' : 'Cookie, Accept-Language'
 
-  // 2. Try cookie (skip if localeCookie is null)
-  if (localeCookie !== null && locale === defaultLocale && cookies.get(localeCookie)) {
-    const cookieLocale = cookies.get(localeCookie)?.value
-    if (cookieLocale && locales.includes(cookieLocale)) {
-      locale = cookieLocale
+  const handler: MiddlewareHandler = async (context, next) => {
+    // A locale already in locals (Astro.rewrite) is kept, not redetected.
+    if (context.locals.locale && context.locals.i18n) {
+      if (context.locals.i18nHandler && context.locals.i18nHandler !== handler) warnTwice()
+      return next()
     }
+
+    const request = resolveRequest(context, routing)
+    const { path, url, locale, partOfPage } = request
+
+    // Coming from a page of another locale is the visitor's choice, whatever link took them here:
+    // no landing to redirect, or a switcher could never reach `/`.
+    const page = asksForPage(context, request)
+    const switched = page && isSwitch(context, request, routing)
+
+    // autoDetect is a redirect hint on the home page only (as the Nuxt module's autoDetectPath '/'):
+    // a visitor whose cookie / Accept-Language prefers another locale is sent to that locale's home.
+    // Only a page view: a redirect in answer to a server island would put a whole page in its slot.
+    const home = page && path === '/'
+    const hinted = autoDetect && home && !switched
+    // only here: reading the headers of a prerendered page makes Astro warn
+    const preferred = hinted
+      ? preferredLocale(path, routing, { cookies: context.cookies, headers: context.request.headers, localeCookie, autoDetect: true })
+      : locale
+    // the home page is a redirect or not depending on the cookie and the header, a part of a page and a switch on the Referer: shared caches key on them
+    const vary = [partOfPage || switched ? 'Referer' : '', autoDetect && home ? varyOn : ''].filter(Boolean).join(', ') || null
+    const target = preferred !== locale || (home && options.redirectToDefault) ? homeOf(preferred, routing) : path
+    if (target !== path) return withVary(context.redirect(withBase(target, base) + url.search, 302), vary)
+
+    Object.assign(context.locals, requestLocals(globalI18n, request, routing, allLocales, handler))
+    const response = await next()
+    // Remembered once it is a page the visitor saw: an endpoint they only fetched is no choice.
+    if (switched && localeCookie !== null && isPageView(context, response)) context.cookies.set(localeCookie, locale, cookieOptions)
+    return withVary(response, vary)
   }
+  return handler
+}
 
-  // 3. Try Accept-Language
-  if (locale === defaultLocale) {
-    try {
-      const detectedFromHeader = detectLocaleFromAcceptLanguage(headers.get('accept-language') ?? undefined, locales)
-      if (detectedFromHeader) {
-        locale = detectedFromHeader
-      }
-    } catch {
-      // Headers may be unavailable in static mode
-      // Fallback to default locale
-    }
+/** What a page reads: a per-request instance sharing the global dictionaries, and the request's model. */
+function requestLocals(globalI18n: AstroI18n, request: I18nRequest, routing: I18nRouting, locales: Locale[], handler: MiddlewareHandler) {
+  const { url, path, locale, route } = request
+  const i18n = globalI18n.fork(locale)
+  i18n.setRoute(route)
+  const strategy = Object.create(routing.strategy) as I18nRoutingStrategy
+  strategy.getCurrentPath = () => path
+  strategy.getRoute = () => ({ fullPath: path + url.search, query: Object.fromEntries(url.searchParams) })
+  return {
+    i18n,
+    locale,
+    defaultLocale: routing.defaultLocale,
+    locales,
+    currentUrl: url,
+    routingStrategy: strategy,
+    i18nBase: routing.base,
+    i18nHandler: handler,
   }
+}
 
-  return locale
+/** A locale's home: the strategy's path for `/` in that locale, else `/<locale>` (an unprefixed URL is the default locale's). */
+function homeOf(locale: string, { strategy, defaultLocale }: I18nRouting): string {
+  const resolved = strategy.resolvePath!('/', locale)
+  const path = typeof resolved === 'string' ? resolved : resolved.path
+  return path || (locale === defaultLocale ? '/' : `/${locale}`)
+}
+
+function withVary(response: Response, vary: string | null): Response {
+  if (vary === null) return response
+  try {
+    response.headers.append('Vary', vary)
+  } catch {
+    // immutable headers (a fetched Response): left as they are
+  }
+  return response
 }

package/src/node.ts

@@ -0,0 +1,51 @@
+/**
+ * `@i18n-micro/astro/node`: reading a locales directory at runtime, for a `src/middleware.ts` of your
+ * own. Node only. `i18nIntegration` bundles the directory by itself, which also works on the edge.
+ */
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Translations } from '@i18n-micro/types'
+import { listTranslationFiles, loadTranslationDir, loadTranslationFiles } from '@i18n-micro/utils/load-dir'
+import type { TranslationFileBuckets } from '@i18n-micro/utils/parse-path'
+
+export interface LoadTranslationsOptions {
+  translationDir: string
+  rootDir?: string
+  disablePageLocales?: boolean
+}
+
+export interface LoadedTranslations extends TranslationFileBuckets<Translations> {}
+
+/** Load all translations from a directory: flat (`en.json`) and nested (`pages/home/en.json`). */
+export function loadTranslationsFromDir(options: LoadTranslationsOptions): LoadedTranslations {
+  const { translationDir, rootDir = process.cwd(), disablePageLocales = false } = options
+  return loadTranslationDir<Translations>(resolve(rootDir, translationDir), disablePageLocales)
+}
+
+/** The directory's dictionaries and the files they came from, for the integration's build. */
+export function readTranslationDir(options: { translationDir: string; rootDir: URL; disablePageLocales?: boolean }) {
+  const dir = resolve(fileURLToPath(options.rootDir), options.translationDir)
+  const files = listTranslationFiles(dir)
+  return {
+    messages: loadTranslationFiles<Translations>(files, options.disablePageLocales),
+    // the folder too: with no file yet, it is what a first one reloads through
+    files: [dir, ...files.map((file) => file.absolutePath)],
+  }
+}
+
+/** Load a directory into an instance, replacing the chunks it finds. */
+export function loadTranslationsIntoI18n(
+  i18n: {
+    addTranslations: (locale: string, translations: Translations, merge?: boolean) => void
+    addRouteTranslations: (locale: string, routeName: string, translations: Translations, merge?: boolean) => void
+    keepMessages?: (messages: Record<string, Translations>, routeMessages: Record<string, Record<string, Translations>>) => void
+  },
+  options: LoadTranslationsOptions,
+): void {
+  const { root, routes } = loadTranslationsFromDir(options)
+  for (const [locale, translations] of Object.entries(root)) i18n.addTranslations(locale, translations, false)
+  for (const [routeName, routeTranslations] of Object.entries(routes)) {
+    for (const [locale, translations] of Object.entries(routeTranslations)) i18n.addRouteTranslations(locale, routeName, translations, false)
+  }
+  i18n.keepMessages?.(root, routes)
+}