@zerotal/i18n 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog — @zerotal/i18n
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `beta`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Added
+
+- Initial release: request-scoped localization for Zerotal.
+- `Translator` with dot-path lookup, fallback-locale resolution, `{var}` / `:var`
+  interpolation, and pipe-segment pluralization (`"none | one | {count} many"`).
+- `I18nConfig` factory (`defaultLocale`, `fallbackLocale`, `supportedLocales`,
+  `resolvers`, `loadPath`, in-memory `catalogs`).
+- `loadCatalogs()` — loads `<locale>.json` files from a directory.
+- Request locale resolution via query string, cookie, and `Accept-Language`.
+- `I18nProvider` + `LocaleMiddleware` — resolve the locale per request and inject
+  `ctx.t()` / `ctx.locale`; AsyncLocalStorage-backed `I18nContext` for the
+  `Lang` facade and the global `t()` helper.
+- Typed error vocabulary (`I18nError` / `CatalogLoadError`, `E_I18N*` codes).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @zerotal/i18n
+
+> Request-scoped internationalization with interpolation, pluralization, and fallback.
+
+Resolves each visitor's locale automatically from the query string, a cookie, or
+the `Accept-Language` header, then translates message keys with interpolation,
+pluralization, and locale fallback. Translations are available on the request
+context (`http.t`), through the `Lang` facade, and via the global `t()` helper.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/i18n
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { I18nProvider } from "@zerotal/i18n";
+
+export default [I18nProvider];
+```
+
+`I18nProvider` registers `LocaleMiddleware`, which resolves the locale for every
+request and injects `ctx.t()` and `ctx.locale`. Configure it in `config/i18n.ts`:
+
+```ts
+// config/i18n.ts
+import { I18nConfig } from "@zerotal/i18n";
+import { env } from "@zerotal/core";
+
+export default I18nConfig({
+  defaultLocale: env("APP_LOCALE", "en"),
+  fallbackLocale: env("APP_FALLBACK_LOCALE", "en"),
+  supportedLocales: ["en", "fr", "es"],
+  resolvers: ["query", "cookie", "accept-header"], // tried in order
+  queryKey: "lang", // ?lang=fr
+  cookieKey: "locale", // locale=fr cookie
+  loadPath: "resources/lang", // <locale>.json catalogs
+});
+```
+
+## Usage
+
+Translate from a controller via the request context:
+
+```ts
+async show({ http }: Context) {
+  http.t("welcome.greeting", { name: "Alice" });       // active locale
+  http.t("welcome.greeting", { name: "Alice" }, "fr"); // explicit locale
+  return http.response.json({ locale: http.locale });
+}
+```
+
+Anywhere else, use the `Lang` facade or the global `t()` helper — both honour the
+active request locale via `I18nContext`:
+
+```ts
+import { Lang, t } from "@zerotal/i18n";
+
+Lang.translate("auth.login.title");
+t("dashboard.welcome");
+
+// Override the resolved locale for the current request:
+Lang.setLocale("fr");
+```
+
+Catalogs support nested or flat dotted keys, `{name}`/`:name` interpolation, and
+pipe-separated pluralization chosen by `count`:
+
+```json
+{
+  "welcome": { "greeting": "Hello, {name}!" },
+  "validation.required": "The :field field is required.",
+  "apples": "no apples | one apple | {count} apples"
+}
+```
+
+```ts
+t("apples", { count: 0 }); // "no apples"
+t("apples", { count: 5 }); // "5 apples"
+```
+
+A key missing in the active locale falls back to `fallbackLocale`; if still
+missing, the key itself is returned (gaps are visible, never thrown).
+
+## Exports
+
+- `Translator` — the core translation service (and `TranslatorOptions`).
+- `I18nProvider` — registers `LocaleMiddleware` and binds the translator.
+- `LocaleMiddleware` — resolves the locale per request and injects `ctx.t`/`ctx.locale`.
+- `I18nContext` — async-local storage holding the active request locale.
+- `Lang`, `t` — facade and global helper that read the active locale.
+- `I18nConfig` / `I18nConfigShape` — config factory and its shape.
+- `loadCatalogs` — load `<locale>.json` catalogs from disk.
+- `resolveLocale`, `parseAcceptLanguage` — locale resolution helpers.
+- Types: `Messages`, `Catalogs`, `Replacements`, `LocaleResolver`.
+- Errors: `I18nError` (`E_I18N`), `CatalogLoadError` (`E_I18N_CATALOG_LOAD`).
+
+## Documentation
+
+- [Internationalization](../../docs/i18n.md)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zerotal/i18n",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "beta",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "sideEffects": [
+    "./src/augment.ts"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Internationalization and localization for Zerotal applications.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/i18n"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/i18n#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/I18nContext.ts

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Request-scoped active locale. `LocaleMiddleware` runs each request inside
+ * `I18nContext.run(locale, …)` so the `Lang` facade and the global `t()` helper
+ * resolve to the right language without threading it through every call.
+ */
+const _storage = new AsyncLocalStorage<string>();
+
+export class I18nContext {
+  /** Execute `callback` with `locale` as the active request locale. */
+  static run<T>(locale: string, callback: () => T): T {
+    return _storage.run(locale, callback);
+  }
+
+  /** The active request locale, or undefined outside a request boundary. */
+  static current(): string | undefined {
+    return _storage.getStore();
+  }
+}

package/src/LocaleMiddleware.ts

@@ -0,0 +1,33 @@
+import type { Pipe, NextFn, HttpContext } from "@zerotal/core";
+import { resolveLocale } from "./locale.ts";
+import { I18nContext } from "./I18nContext.ts";
+import type { Translator } from "./Translator.ts";
+import type { I18nConfigShape } from "./config.ts";
+
+/**
+ * Resolves the request locale, exposes `ctx.locale` + `ctx.t()`, and runs the
+ * rest of the pipeline inside `I18nContext.run()` so the `Lang` facade and the
+ * global `t()` helper see the right locale. Configured by I18nProvider via
+ * `LocaleMiddleware.configure()` and registered with `app.useOnce()`.
+ */
+export class LocaleMiddleware implements Pipe<HttpContext> {
+  private static _translator: Translator | null = null;
+  private static _config: I18nConfigShape | null = null;
+
+  static configure(translator: Translator, config: I18nConfigShape): void {
+    LocaleMiddleware._translator = translator;
+    LocaleMiddleware._config = config;
+  }
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const translator = LocaleMiddleware._translator;
+    const config = LocaleMiddleware._config;
+    if (!translator || !config) return next();
+
+    const locale = resolveLocale(http.request, config);
+    http.locale = locale;
+    http.t = (key, replacements, loc) => translator.translate(key, replacements, loc ?? locale);
+
+    return I18nContext.run(locale, () => next());
+  }
+}

package/src/Translator.ts

@@ -0,0 +1,107 @@
+import { I18nContext } from "./I18nContext.ts";
+import type { Catalogs, Messages, Replacements } from "./types.ts";
+
+export interface TranslatorOptions {
+  catalogs: Catalogs;
+  defaultLocale: string;
+  fallbackLocale: string;
+}
+
+/**
+ * Resolves translation keys against per-locale catalogs, with fallback,
+ * interpolation, and pluralization. Resolved from the container as `i18n`.
+ */
+export class Translator {
+  private readonly catalogs: Catalogs;
+  readonly defaultLocale: string;
+  readonly fallbackLocale: string;
+
+  constructor(opts: TranslatorOptions) {
+    this.catalogs = opts.catalogs;
+    this.defaultLocale = opts.defaultLocale;
+    this.fallbackLocale = opts.fallbackLocale;
+  }
+
+  /** Loaded locales. */
+  get locales(): string[] {
+    return Object.keys(this.catalogs);
+  }
+
+  /** Merge messages into a locale's catalog (used by tooling/tests). */
+  addCatalog(locale: string, messages: Messages): void {
+    this.catalogs[locale] = { ...(this.catalogs[locale] ?? {}), ...messages };
+  }
+
+  /** Active locale: explicit arg → request context → default. */
+  private _resolve(locale?: string): string {
+    return locale ?? I18nContext.current() ?? this.defaultLocale;
+  }
+
+  /** True if `key` exists in the given (or active) locale or the fallback. */
+  has(key: string, locale?: string): boolean {
+    const loc = this._resolve(locale);
+    return (
+      this._lookup(key, loc) !== undefined || this._lookup(key, this.fallbackLocale) !== undefined
+    );
+  }
+
+  /**
+   * Translate `key`. Missing keys return the key itself (so the UI degrades
+   * visibly rather than throwing).
+   *
+   * @example
+   * t.translate('welcome.greeting', { name: 'Alice' }, 'fr');
+   * t.translate('apples', { count: 2 }); // pipe-pluralized
+   */
+  translate(key: string, replacements: Replacements = {}, locale?: string): string {
+    const loc = this._resolve(locale);
+    let msg = this._lookup(key, loc);
+    if (msg === undefined && loc !== this.fallbackLocale) {
+      msg = this._lookup(key, this.fallbackLocale);
+    }
+    if (msg === undefined) return key;
+    if (typeof replacements.count === "number") {
+      msg = this._pluralize(msg, replacements.count);
+    }
+    return this._interpolate(msg, replacements);
+  }
+
+  /** Look up a key as a flat dotted key first, then as a nested path. */
+  private _lookup(key: string, locale: string): string | undefined {
+    const cat = this.catalogs[locale];
+    if (!cat) return undefined;
+    const flat = (cat as Record<string, unknown>)[key];
+    if (typeof flat === "string") return flat;
+    let node: unknown = cat;
+    for (const part of key.split(".")) {
+      if (node && typeof node === "object" && part in (node as object)) {
+        node = (node as Record<string, unknown>)[part];
+      } else {
+        return undefined;
+      }
+    }
+    return typeof node === "string" ? node : undefined;
+  }
+
+  /**
+   * Choose a pipe-separated segment by count.
+   *  - 2 segments: `singular | plural` (count === 1 → first).
+   *  - 3+ segments: `zero | one | many` (count 0 → first, 1 → second, else last).
+   */
+  private _pluralize(message: string, count: number): string {
+    const segs = message.split("|").map((s) => s.trim());
+    if (segs.length === 1) return segs[0]!;
+    if (segs.length === 2) return count === 1 ? segs[0]! : segs[1]!;
+    if (count === 0) return segs[0]!;
+    if (count === 1) return segs[1]!;
+    return segs[segs.length - 1]!;
+  }
+
+  /** Replace `{name}` and `:name` placeholders from `replacements`. */
+  private _interpolate(message: string, replacements: Replacements): string {
+    return message.replace(/\{(\w+)\}|:(\w+)/g, (match, curly: string, colon: string) => {
+      const key = curly ?? colon;
+      return key in replacements ? String(replacements[key]) : match;
+    });
+  }
+}

package/src/augment.ts

@@ -0,0 +1,22 @@
+import type { Translator } from "./Translator.ts";
+import type { Replacements } from "./types.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    /** The translation service — registered by I18nProvider. */
+    i18n: Translator;
+  }
+
+  interface HttpContext {
+    /**
+     * Translate a key using this request's resolved locale.
+     *
+     * @example
+     * ctx.t('welcome.greeting', { name: 'Alice' });
+     * ctx.t('welcome.greeting', { name: 'Alice' }, 'fr'); // explicit locale
+     */
+    t(key: string, replacements?: Replacements, locale?: string): string;
+  }
+}
+
+export {};

package/src/config.ts

@@ -0,0 +1,55 @@
+import { deepMerge } from "@zerotal/core";
+import type { Catalogs, LocaleResolver } from "./types.ts";
+
+export interface I18nConfigShape {
+  /** Locale used when no resolver matches. */
+  defaultLocale: string;
+  /** Locale consulted when a key is missing in the active locale. */
+  fallbackLocale: string;
+  /** Locales the app accepts; resolvers only return one of these. */
+  supportedLocales: string[];
+  /** Request resolvers, tried in order. Default: query -> cookie -> accept-header. */
+  resolvers: LocaleResolver[];
+  /** Query-string key for the `query` resolver. Default: `lang`. */
+  queryKey: string;
+  /** Cookie name for the `cookie` resolver. Default: `locale`. */
+  cookieKey: string;
+  /** Directory of `<locale>.json` catalogs, loaded on boot. */
+  loadPath?: string;
+  /** In-memory catalogs, merged over anything loaded from `loadPath`. */
+  catalogs?: Catalogs;
+}
+
+/**
+ * Build the i18n configuration block.
+ *
+ * @example
+ * // config/i18n.ts
+ * import { I18nConfig } from '@zerotal/i18n';
+ * export default I18nConfig({
+ *   supportedLocales: ['en', 'fr', 'es'],
+ *   loadPath: 'resources/lang',
+ * });
+ */
+export function I18nConfig(options: Partial<I18nConfigShape> = {}): I18nConfigShape {
+  // `fallbackLocale` and `supportedLocales` default off the chosen `defaultLocale`,
+  // so the defaults are computed before the merge. deepMerge then applies any
+  // explicit overrides (and replaces the `supportedLocales`/`resolvers` arrays).
+  const defaultLocale = options.defaultLocale ?? "en";
+  const defaults: I18nConfigShape = {
+    defaultLocale,
+    fallbackLocale: defaultLocale,
+    supportedLocales: [defaultLocale],
+    resolvers: ["query", "cookie", "accept-header"],
+    queryKey: "lang",
+    cookieKey: "locale",
+  };
+  return deepMerge(defaults, options);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    i18n: I18nConfigShape;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,20 @@
+import { ZerotalError } from "@zerotal/core";
+
+/** Base class for all @zerotal/i18n errors. */
+export class I18nError extends ZerotalError {
+  constructor(message: string, code = "E_I18N", status = 500, context?: Record<string, unknown>) {
+    super(message, code, status, context);
+  }
+}
+
+/** Thrown when a catalog file exists but cannot be read/parsed as JSON. */
+export class CatalogLoadError extends I18nError {
+  constructor(file: string, cause: unknown) {
+    super(
+      `[Zerotal i18n] Failed to load catalog "${file}": ${(cause as Error)?.message ?? String(cause)}`,
+      "E_I18N_CATALOG_LOAD",
+      500,
+      { file },
+    );
+  }
+}

package/src/facades/Lang.ts

@@ -0,0 +1,22 @@
+import { createFacade } from "@zerotal/core";
+import type { Replacements } from "../types.ts";
+
+/**
+ * Facade for the translation service (container key `i18n`). Resolves against
+ * the active request locale via I18nContext.
+ *
+ * @example
+ * import { Lang } from '@zerotal/i18n';
+ * Lang.translate('welcome.greeting', { name: 'Alice' });
+ */
+export const Lang = createFacade<"i18n">("i18n");
+
+/**
+ * Convenience global translation helper — handy as a view global.
+ *
+ * @example
+ * t('messages.unread', { count: 5 });
+ */
+export function t(key: string, replacements?: Replacements, locale?: string): string {
+  return Lang.translate(key, replacements, locale);
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// @zerotal/i18n — public API
+
+// Core service
+export { Translator } from "./Translator.ts";
+export type { TranslatorOptions } from "./Translator.ts";
+
+// Request-scoped locale
+export { I18nContext } from "./I18nContext.ts";
+
+// Provider + middleware
+export { I18nProvider } from "./provider/I18nProvider.ts";
+export { LocaleMiddleware } from "./LocaleMiddleware.ts";
+
+// Facade + helper
+export { Lang, t } from "./facades/Lang.ts";
+
+// Config
+export { I18nConfig } from "./config.ts";
+export type { I18nConfigShape } from "./config.ts";
+
+// Catalog loading + locale resolution
+export { loadCatalogs } from "./loadCatalogs.ts";
+export { resolveLocale, parseAcceptLanguage } from "./locale.ts";
+
+// Types
+export type { Messages, Catalogs, Replacements, LocaleResolver } from "./types.ts";
+
+// Typed error vocabulary
+export * from "./errors.ts";
+
+// Side-effect: activate @zerotal/core HttpContext + ContainerBindings augmentation.
+import "./augment.ts";

package/src/loadCatalogs.ts

@@ -0,0 +1,35 @@
+import type { Catalogs, Messages } from "./types.ts";
+import { CatalogLoadError } from "./errors.ts";
+
+/**
+ * Load `<locale>.json` files from `dir` into a catalog map. A missing directory
+ * yields an empty map; a malformed JSON file throws `CatalogLoadError`.
+ *
+ * @example
+ * const catalogs = await loadCatalogs('resources/lang'); // { en: {...}, fr: {...} }
+ */
+export async function loadCatalogs(dir: string): Promise<Catalogs> {
+  const out: Catalogs = {};
+  const entries: string[] = [];
+  try {
+    const glob = new Bun.Glob("*.json");
+    for await (const rel of glob.scan({ cwd: dir, onlyFiles: true })) {
+      entries.push(rel);
+    }
+  } catch {
+    return out; // no directory — nothing to load
+  }
+  for (const rel of entries) {
+    const locale = rel
+      .replace(/\.json$/, "")
+      .replace(/\\/g, "/")
+      .split("/")
+      .pop()!;
+    try {
+      out[locale] = (await Bun.file(`${dir}/${rel}`).json()) as Messages;
+    } catch (err) {
+      throw new CatalogLoadError(`${dir}/${rel}`, err);
+    }
+  }
+  return out;
+}

package/src/locale.ts

@@ -0,0 +1,54 @@
+import type { I18nConfigShape } from "./config.ts";
+
+/** Parse an `Accept-Language` header into tags ordered by descending quality. */
+export function parseAcceptLanguage(header: string | null): string[] {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((part) => {
+      const [tag, q] = part.trim().split(";q=");
+      return { tag: (tag ?? "").trim().toLowerCase(), q: q ? parseFloat(q) : 1 };
+    })
+    .filter((x) => x.tag.length > 0)
+    .sort((a, b) => b.q - a.q)
+    .map((x) => x.tag);
+}
+
+/** Read a single cookie value from a Cookie header. */
+function _cookie(header: string | null, name: string): string | null {
+  if (!header) return null;
+  for (const pair of header.split(";")) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) continue;
+    if (pair.slice(0, eq).trim() === name) {
+      return decodeURIComponent(pair.slice(eq + 1).trim());
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the locale for a request by trying each configured resolver in order.
+ * Only returns a locale present in `supportedLocales`; otherwise `defaultLocale`.
+ */
+export function resolveLocale(request: Request, config: I18nConfigShape): string {
+  const supported = config.supportedLocales;
+  const ok = (l: string | null | undefined): l is string => !!l && supported.includes(l);
+
+  for (const resolver of config.resolvers) {
+    if (resolver === "query") {
+      const v = new URL(request.url).searchParams.get(config.queryKey);
+      if (ok(v)) return v;
+    } else if (resolver === "cookie") {
+      const v = _cookie(request.headers.get("cookie"), config.cookieKey);
+      if (ok(v)) return v;
+    } else if (resolver === "accept-header") {
+      for (const tag of parseAcceptLanguage(request.headers.get("accept-language"))) {
+        if (supported.includes(tag)) return tag;
+        const base = tag.split("-")[0]!; // 'en-US' → 'en'
+        if (ok(base)) return base;
+      }
+    }
+  }
+  return config.defaultLocale;
+}

package/src/provider/I18nProvider.ts

@@ -0,0 +1,54 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import { Translator } from "../Translator.ts";
+import { loadCatalogs } from "../loadCatalogs.ts";
+import { LocaleMiddleware } from "../LocaleMiddleware.ts";
+import { I18nConfig } from "../config.ts";
+import type { I18nConfigShape } from "../config.ts";
+import "../augment.ts";
+
+/**
+ * Registers the translation service and wires request-locale resolution.
+ *
+ * @example
+ * // bootstrap/providers.ts
+ * import { I18nProvider } from '@zerotal/i18n';
+ * export default [I18nProvider];
+ *
+ * // config/i18n.ts
+ * import { I18nConfig } from '@zerotal/i18n';
+ * export default I18nConfig({ supportedLocales: ['en', 'fr'], loadPath: 'resources/lang' });
+ */
+export class I18nProvider extends ServiceProvider {
+  static override provides = ["i18n"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test", "repl"];
+
+  private async _resolveConfig(): Promise<I18nConfigShape> {
+    const cfg = (await this.app.container.make("config")) as {
+      get<T>(path: string): T | undefined;
+    };
+    return I18nConfig(cfg.get<Partial<I18nConfigShape>>("i18n") ?? {});
+  }
+
+  override onRegister(): void {
+    this.app.container.singleton("i18n", async () => {
+      const config = await this._resolveConfig();
+      const catalogs = {
+        ...(config.loadPath ? await loadCatalogs(config.loadPath) : {}),
+        ...(config.catalogs ?? {}),
+      };
+      return new Translator({
+        catalogs,
+        defaultLocale: config.defaultLocale,
+        fallbackLocale: config.fallbackLocale,
+      });
+    });
+  }
+
+  override async onBooting(): Promise<void> {
+    const translator = (await this.app.container.make("i18n")) as Translator;
+    const config = await this._resolveConfig();
+    LocaleMiddleware.configure(translator, config);
+    this.app.useOnce(LocaleMiddleware as never);
+  }
+}

package/src/types.ts

@@ -0,0 +1,11 @@
+/** A translation catalog — nested objects and/or flat dotted keys, leaves are strings. */
+export type Messages = { [key: string]: string | Messages };
+
+/** locale → messages */
+export type Catalogs = Record<string, Messages>;
+
+/** Interpolation values; `count` additionally drives pluralization. */
+export type Replacements = Record<string, string | number>;
+
+/** Built-in request locale resolvers, applied in order. */
+export type LocaleResolver = "query" | "cookie" | "accept-header";