@alxia/i18n 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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,109 @@
+# @alxia/i18n
+
+Translations for [alxia](https://www.npmjs.com/package/@alxia/core), on
+[`@nxgt/i18n`](https://www.npmjs.com/package/@nxgt/i18n): `t()` bound to the
+request's language, keys typed by your catalogue, ICU messages — plurals,
+selects, numbers.
+
+```sh
+bun add @alxia/i18n @alxia/language @nxgt/i18n@^2 @alxia/core
+bun add -d typescript
+```
+
+## Usage
+
+```ts
+import { alxia } from '@alxia/core';
+import { createI18n } from '@alxia/i18n';
+import { resources as shared } from '@nxgt/i18n';
+
+const en = { ...shared.en, cart: { items: '{count, plural, =0 {No items} one {One item} other {# items}}' } };
+const fr = { ...shared.fr, cart: { items: '{count, plural, =0 {Aucun article} one {Un article} other {# articles}}' } };
+
+export const i18n = createI18n({ resources: { en, fr }, fallback: 'en' });
+
+const app = alxia()
+	.use(i18n)
+	.get('/cart', ({ t, reply }) => reply(200, t('cart.items', { count: 3 }))); // '3 articles' in French
+
+app.listen(3000);
+```
+
+- **The language** is `@alxia/language`'s, among the catalogues' languages:
+  the query, a cookie, `Accept-Language`, then `fallback`. Its options pass
+  through: `createI18n({ resources, fallback, order: ['path', 'header'] })`.
+- **Keys** are typed by the fallback's catalogue: `t('cart.itmes')` is a
+  compile error. A key a language lacks answers itself.
+- **`@nxgt/i18n`'s shared keys** — `errors.not-found`, `zod.*` — are yours by
+  spreading its `resources` into your catalogues.
+
+## Reading the app's context
+
+Annotate `resolve`'s parameter to speak the language a signed-in user saved.
+The plugin then requires what it reads: an app that does not give `user`
+before it cannot use it.
+
+```ts
+import { alxia, type BaseContext } from '@alxia/core';
+import { createI18n } from '@alxia/i18n';
+
+const en = { home: { title: 'Welcome' } };
+const fr = { home: { title: 'Bienvenue' } };
+
+const auth = alxia().derive(({ request }) => ({
+	user: request.headers.has('authorization') ? { language: 'fr' } : null, // your sign-in
+}));
+
+const byUser = createI18n({
+	resources: { en, fr },
+	fallback: 'en',
+	order: ['query'],
+	resolve: ({ user }: BaseContext & { user: { language: string } | null }) => user?.language,
+});
+
+alxia().use(auth).use(byUser); // auth derives user
+alxia().use(byUser); // a compile error: this app gives no `user`
+```
+
+Unannotated, `resolve` reads the request alone and the plugin requires
+nothing; annotated `any`, the plugin is refused on every app.
+
+## Anywhere
+
+```ts
+// a service, or an error's message: no language passed
+export const describeCart = (count: number) => i18n.t('cart.items', { count });
+```
+
+`i18n.t()` translates in the language of the request it runs in — through
+every `await`, an `onError` hook included — and in the fallback outside
+one, or before the language is read: in an `onRequest` hook, or a route
+declared before the plugin
+([troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/i18n/docs/troubleshooting.md#i18nt-answers-in-the-fallback-before-the-language-is-read)).
+`i18n.language()` says which.
+
+### `@nxgt/i18n`'s own `translate`
+
+`createI18n()` registers the request's language as one of `@nxgt/i18n`'s
+language sources: its `getLanguage()` and `translate` — and every nxgt
+package that translates through them, an error's message — speak the alxia
+request's language too.
+
+## Cached responses
+
+A response in the request's language varies by what decided it: give
+`@alxia/cache` the same headers, `vary: ['accept-language', 'cookie']`.
+
+## API
+
+| export | |
+| --- | --- |
+| `createI18n({ resources, fallback, …languageOptions })` | the plugin — routes after it read `t` and `language` — with `t()`, `language()` and `supported` |
+| `I18nOptions` | its options: `resources`, `fallback`, and every `@alxia/language` option but `supported`; `resolve` may be annotated to read the app's context |
+| `KeyOf<Catalogue>`, `Translate<Key>`, `Catalogues`, `I18nContext<Key>` | its types |
+
+## Documentation
+
+- [Guide](https://github.com/softistx/alxia/tree/develop/packages/i18n/docs): the catalogues and every option, reading what an earlier plugin added, what the routes read, ICU messages and typed keys, `t()` outside a route, and `@nxgt/i18n`'s own `translate`.
+- [Troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/i18n/docs/troubleshooting.md): an error, a key shown instead of a message, or a response in the wrong language, and what to do about it.
+- [Roadmap](https://github.com/softistx/alxia/blob/develop/packages/i18n/docs/roadmap.md): what is coming, and what is not planned.

package/dist/i18n.d.ts

@@ -0,0 +1,56 @@
+import { type BaseContext, type RequiresOf } from '@alxia/core';
+import { type LanguageOptions } from '@alxia/language';
+import { type Path, type TranslationContext } from '@nxgt/i18n';
+/** Catalogues by language: `{ en: { greeting: 'Hello {name}' }, fr: … }`. */
+export type Catalogues = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/** Every key of a catalogue, dotted: `users.greeting`. */
+export type KeyOf<Catalogue> = Path<Catalogue> & string;
+/** A translation of a key, in a language, formatted with ICU's `context`. */
+export type Translate<Key extends string> = (key: Key, context?: TranslationContext) => string;
+/**
+ * `Ctx` is the type `resolve`'s parameter is annotated with —
+ * `BaseContext & { user: User }`, or `{ user: User }` alone — and
+ * `BaseContext` when it is not: what the plugin then requires of the app.
+ */
+export interface I18nOptions<C extends Catalogues, Fallback extends keyof C & string, Ctx extends object = BaseContext> extends Omit<LanguageOptions<keyof C & string, Ctx>, 'supported' | 'fallback'> {
+    /**
+     * The catalogues, one per language: their keys are the languages
+     * supported. Spread `@nxgt/i18n`'s `resources` into them for its shared
+     * keys — `errors.not-found`, `zod.*`.
+     */
+    readonly resources: C;
+    /** The language spoken when the request names none, and whose keys type `t`. */
+    readonly fallback: Fallback;
+}
+/** What the routes behind the plugin read. */
+export interface I18nContext<Key extends string> {
+    /** Translates into the request's language. */
+    readonly t: Translate<Key>;
+}
+/**
+ * Translations, as a plugin, on [`@nxgt/i18n`](https://www.npmjs.com/package/@nxgt/i18n):
+ * `@alxia/language` reads the request's language among the catalogues', and
+ * the routes declared after it read `language` and `t`, bound to it. Keys
+ * are typed by the fallback's catalogue; messages are ICU — plurals,
+ * selects, numbers — and a missing key answers itself.
+ *
+ * The plugin's own `t()` translates anywhere a request runs — a service, an
+ * error's message — in that request's language, and in the fallback outside.
+ *
+ * ```ts
+ * const i18n = createI18n({ resources: { en, fr }, fallback: 'en' });
+ * app.use(i18n).get('/', ({ t, reply }) => reply(200, t('home.title')));
+ * ```
+ *
+ * The plugin registers the request's language as one of `@nxgt/i18n`'s
+ * language sources, so its own `getLanguage()` and `translate` — and every
+ * nxgt package that translates through them — speak it too.
+ */
+export declare function createI18n<const C extends Catalogues, const Fallback extends keyof C & string, Ctx extends object = BaseContext>(options: I18nOptions<C, Fallback, Ctx>): import("@alxia/core").Alxia<RequiresOf<Ctx, "resolve"> & import("@alxia/core").Empty & import("@alxia/language").LanguageContext<keyof C & string> & I18nContext<KeyOf<C[Fallback]>>, import("@alxia/core").Empty & {}, "", never> & import("@alxia/core").Requiring<RequiresOf<Ctx, "resolve">> & {
+    /** Translates into the current request's language, or the fallback outside one. */
+    t: Translate<KeyOf<C[Fallback]>>;
+    /** The current request's language, or the fallback outside one. */
+    language: () => keyof C & string;
+    supported: (keyof C & string)[];
+};
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,KAAK,eAAe,EAAY,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAEN,KAAK,IAAI,EAET,KAAK,kBAAkB,EACvB,MAAM,YAAY,CAAC;AAEpB,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG,QAAQ,CAChC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CACjD,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC;AAExD,6EAA6E;AAC7E,MAAM,MAAM,SAAS,CAAC,GAAG,SAAS,MAAM,IAAI,CAC3C,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE,kBAAkB,KACxB,MAAM,CAAC;AAEZ;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAC3B,CAAC,SAAS,UAAU,EACpB,QAAQ,SAAS,MAAM,CAAC,GAAG,MAAM,EACjC,GAAG,SAAS,MAAM,GAAG,WAAW,CAC/B,SAAQ,IAAI,CACZ,eAAe,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,CAAC,EACtC,WAAW,GAAG,UAAU,CACxB;IACD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC5B;AAWD,8CAA8C;AAC9C,MAAM,WAAW,WAAW,CAAC,GAAG,SAAS,MAAM;IAC9C,8CAA8C;IAC9C,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CACzB,KAAK,CAAC,CAAC,SAAS,UAAU,EAC1B,KAAK,CAAC,QAAQ,SAAS,MAAM,CAAC,GAAG,MAAM,EACvC,GAAG,SAAS,MAAM,GAAG,WAAW,EAC/B,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC;IAiDtC,mFAAmF;OACvB,SAAS,oBAAK;IAC1E,mEAAmE;;;EAIpE"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { type Catalogues, createI18n, type I18nContext, type I18nOptions, type KeyOf, type Translate, } from './i18n';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,UAAU,EACf,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,KAAK,EACV,KAAK,SAAS,GACd,MAAM,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,45 @@
+// src/i18n.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+import { definePlugin } from "@alxia/core";
+import { language } from "@alxia/language";
+import {
+  createTranslator,
+  registerLanguageSource
+} from "@nxgt/i18n";
+var requests = new AsyncLocalStorage;
+var requestLanguage = () => requests.getStore()?.language;
+function createI18n(options) {
+  const { resources, fallback, resolve, ...detect } = options;
+  const supported = Object.keys(resources);
+  const translator = createTranslator(resources);
+  const current = new AsyncLocalStorage;
+  const spoken = () => current.getStore()?.language ?? fallback;
+  const translate = (lang) => (key, context) => translator(key, context, lang);
+  registerLanguageSource(requestLanguage);
+  const detected = language({
+    ...detect,
+    supported,
+    fallback,
+    ...resolve === undefined ? {} : { resolve }
+  });
+  const plugin = definePlugin()((app) => app.around((_ctx, next) => current.run({}, () => requests.run({}, next))).use(detected).derive(({ language: lang }) => {
+    const own = current.getStore();
+    if (own !== undefined)
+      own.language = lang;
+    const heard = requests.getStore();
+    if (heard !== undefined)
+      heard.language ??= lang;
+    return { t: translate(lang) };
+  }));
+  return Object.assign(plugin, {
+    t: (key, context) => translate(spoken())(key, context),
+    language: spoken,
+    supported
+  });
+}
+export {
+  createI18n
+};
+
+//# debugId=700D328B5FADEAA064756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/i18n.ts"],
+  "sourcesContent": [
+    "import { AsyncLocalStorage } from 'node:async_hooks';\nimport { type BaseContext, definePlugin, type RequiresOf } from '@alxia/core';\nimport { type LanguageOptions, language } from '@alxia/language';\nimport {\n\tcreateTranslator,\n\ttype Path,\n\tregisterLanguageSource,\n\ttype TranslationContext,\n} from '@nxgt/i18n';\n\n/** Catalogues by language: `{ en: { greeting: 'Hello {name}' }, fr: … }`. */\nexport type Catalogues = Readonly<\n\tRecord<string, Readonly<Record<string, unknown>>>\n>;\n\n/** Every key of a catalogue, dotted: `users.greeting`. */\nexport type KeyOf<Catalogue> = Path<Catalogue> & string;\n\n/** A translation of a key, in a language, formatted with ICU's `context`. */\nexport type Translate<Key extends string> = (\n\tkey: Key,\n\tcontext?: TranslationContext,\n) => string;\n\n/**\n * `Ctx` is the type `resolve`'s parameter is annotated with —\n * `BaseContext & { user: User }`, or `{ user: User }` alone — and\n * `BaseContext` when it is not: what the plugin then requires of the app.\n */\nexport interface I18nOptions<\n\tC extends Catalogues,\n\tFallback extends keyof C & string,\n\tCtx extends object = BaseContext,\n> extends Omit<\n\t\tLanguageOptions<keyof C & string, Ctx>,\n\t\t'supported' | 'fallback'\n\t> {\n\t/**\n\t * The catalogues, one per language: their keys are the languages\n\t * supported. Spread `@nxgt/i18n`'s `resources` into them for its shared\n\t * keys — `errors.not-found`, `zod.*`.\n\t */\n\treadonly resources: C;\n\t/** The language spoken when the request names none, and whose keys type `t`. */\n\treadonly fallback: Fallback;\n}\n\n/**\n * The request's language as `@nxgt/i18n` hears it: the first an i18n plugin\n * read, when an app uses several. Opened fresh by each plugin's `around`.\n */\nconst requests = new AsyncLocalStorage<{ language?: string }>();\n\n/** `@nxgt/i18n`'s source: one function, so registering it again keeps one. */\nconst requestLanguage = () => requests.getStore()?.language;\n\n/** What the routes behind the plugin read. */\nexport interface I18nContext<Key extends string> {\n\t/** Translates into the request's language. */\n\treadonly t: Translate<Key>;\n}\n\n/**\n * Translations, as a plugin, on [`@nxgt/i18n`](https://www.npmjs.com/package/@nxgt/i18n):\n * `@alxia/language` reads the request's language among the catalogues', and\n * the routes declared after it read `language` and `t`, bound to it. Keys\n * are typed by the fallback's catalogue; messages are ICU — plurals,\n * selects, numbers — and a missing key answers itself.\n *\n * The plugin's own `t()` translates anywhere a request runs — a service, an\n * error's message — in that request's language, and in the fallback outside.\n *\n * ```ts\n * const i18n = createI18n({ resources: { en, fr }, fallback: 'en' });\n * app.use(i18n).get('/', ({ t, reply }) => reply(200, t('home.title')));\n * ```\n *\n * The plugin registers the request's language as one of `@nxgt/i18n`'s\n * language sources, so its own `getLanguage()` and `translate` — and every\n * nxgt package that translates through them — speak it too.\n */\nexport function createI18n<\n\tconst C extends Catalogues,\n\tconst Fallback extends keyof C & string,\n\tCtx extends object = BaseContext,\n>(options: I18nOptions<C, Fallback, Ctx>) {\n\ttype Language = keyof C & string;\n\ttype Key = KeyOf<C[Fallback]>;\n\tconst { resources, fallback, resolve, ...detect } = options;\n\tconst supported = Object.keys(resources) as Language[];\n\tconst translator = createTranslator<Key>(\n\t\tresources as Record<string, unknown>,\n\t);\n\t/**\n\t * This plugin's language for the request running, once `@alxia/language`\n\t * has read it. A global `around` hook opens it fresh for each request —\n\t * one made from inside another included — so it holds for everything the\n\t * request runs, `onError` hooks too, which run after the route failed.\n\t */\n\tconst current = new AsyncLocalStorage<{ language?: Language }>();\n\tconst spoken = (): Language => current.getStore()?.language ?? fallback;\n\tconst translate =\n\t\t(lang: Language): Translate<Key> =>\n\t\t(key, context) =>\n\t\t\ttranslator(key, context, lang as never);\n\n\t// nxgt's own getLanguage() and translate speak the request's language too.\n\tregisterLanguageSource(requestLanguage);\n\n\t// The plugin requires what `resolve` reads, and `use` checks the app gives\n\t// it; the `language()` inside is then handed `resolve` as reading only\n\t// `BaseContext`, since a context that is a type parameter defers the check.\n\tconst detected = language<Language>({\n\t\t...detect,\n\t\tsupported,\n\t\tfallback,\n\t\t...(resolve === undefined\n\t\t\t? {}\n\t\t\t: { resolve: resolve as (ctx: BaseContext) => string | undefined }),\n\t});\n\tconst plugin = definePlugin<RequiresOf<Ctx, 'resolve'>>()((app) =>\n\t\tapp\n\t\t\t.around((_ctx, next) => current.run({}, () => requests.run({}, next)))\n\t\t\t.use(detected)\n\t\t\t.derive(({ language: lang }): I18nContext<Key> => {\n\t\t\t\tconst own = current.getStore();\n\t\t\t\tif (own !== undefined) own.language = lang;\n\t\t\t\tconst heard = requests.getStore();\n\t\t\t\tif (heard !== undefined) heard.language ??= lang;\n\t\t\t\treturn { t: translate(lang) };\n\t\t\t}),\n\t);\n\n\treturn Object.assign(plugin, {\n\t\t/** Translates into the current request's language, or the fallback outside one. */\n\t\tt: ((key, context) => translate(spoken())(key, context)) as Translate<Key>,\n\t\t/** The current request's language, or the fallback outside one. */\n\t\tlanguage: spoken,\n\t\tsupported,\n\t});\n}\n"
+  ],
+  "mappings": ";AAAA;AACA;AACA;AACA;AAAA;AAAA;AAAA;AAgDA,IAAM,WAAW,IAAI;AAGrB,IAAM,kBAAkB,MAAM,SAAS,SAAS,GAAG;AA2B5C,SAAS,UAIf,CAAC,SAAwC;AAAA,EAGzC,QAAQ,WAAW,UAAU,YAAY,WAAW;AAAA,EACpD,MAAM,YAAY,OAAO,KAAK,SAAS;AAAA,EACvC,MAAM,aAAa,iBAClB,SACD;AAAA,EAOA,MAAM,UAAU,IAAI;AAAA,EACpB,MAAM,SAAS,MAAgB,QAAQ,SAAS,GAAG,YAAY;AAAA,EAC/D,MAAM,YACL,CAAC,SACD,CAAC,KAAK,YACL,WAAW,KAAK,SAAS,IAAa;AAAA,EAGxC,uBAAuB,eAAe;AAAA,EAKtC,MAAM,WAAW,SAAmB;AAAA,OAChC;AAAA,IACH;AAAA,IACA;AAAA,OACI,YAAY,YACb,CAAC,IACD,EAAE,QAA6D;AAAA,EACnE,CAAC;AAAA,EACD,MAAM,SAAS,aAAyC,EAAE,CAAC,QAC1D,IACE,OAAO,CAAC,MAAM,SAAS,QAAQ,IAAI,CAAC,GAAG,MAAM,SAAS,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,EACpE,IAAI,QAAQ,EACZ,OAAO,GAAG,UAAU,WAA6B;AAAA,IACjD,MAAM,MAAM,QAAQ,SAAS;AAAA,IAC7B,IAAI,QAAQ;AAAA,MAAW,IAAI,WAAW;AAAA,IACtC,MAAM,QAAQ,SAAS,SAAS;AAAA,IAChC,IAAI,UAAU;AAAA,MAAW,MAAM,aAAa;AAAA,IAC5C,OAAO,EAAE,GAAG,UAAU,IAAI,EAAE;AAAA,GAC5B,CACH;AAAA,EAEA,OAAO,OAAO,OAAO,QAAQ;AAAA,IAE5B,GAAI,CAAC,KAAK,YAAY,UAAU,OAAO,CAAC,EAAE,KAAK,OAAO;AAAA,IAEtD,UAAU;AAAA,IACV;AAAA,EACD,CAAC;AAAA;",
+  "debugId": "700D328B5FADEAA064756E2164756E21",
+  "names": []
+}

package/docs/README.md

@@ -0,0 +1,13 @@
+# @alxia/i18n documentation
+
+The [package README](../README.md) is the short version. This folder is
+the long one: the catalogues and every option, what the routes behind the
+plugin read, how messages are formatted and keys typed, where the
+request's language reaches and where it does not, and what to do when a
+response shows a key or the wrong language.
+
+| Page | Read it when |
+| --- | --- |
+| [Guide](guide.md) | writing the catalogues, choosing where the language is read from, reading a user's saved language from an earlier plugin, typing a function that translates, translating in a service or an error handler, caching the responses, or testing them |
+| [Troubleshooting](troubleshooting.md) | `createI18n()` threw at start-up, `tsc` refused a key, an option or `use(i18n)`, the log shows an ICU error, or a response shows a key or the wrong language |
+| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |