@kitr/i18n 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+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

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @kitr/i18n
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Translations.** Translate your app into several languages with typed keys.
+
+```sh
+pnpm kitr add i18n
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/i18n`.
+
+Built on react-i18next.
+
+Read the guide at https://kitr.dev/packages/i18n.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import i18next, { InitOptions, i18n } from "i18next";
+export * from "react-i18next";
+/**
+ * The options in `config/i18n.ts`: your strings per locale, the fallback locale and detection.
+ * Any other i18next init option passes straight through.
+ */
+export interface I18nConfig extends Omit<InitOptions, 'resources' | 'lng'> {
+  /** Every locale's strings, keyed by locale then namespace: `{ en: { common: { hello: 'Hello' } } }`. */
+  resources: Record<string, Record<string, Record<string, unknown>>>;
+  /** The locale used when nothing better matches, and the fallback for missing keys. */
+  defaultLocale: string;
+  /** The locales the app supports. Default: the keys of `resources`. */
+  locales?: string[];
+  /** Detect from `navigator.language` (client) or `Accept-Language` (server). Default true. */
+  detect?: boolean;
+  /** Query/cookie/storage key for an explicit choice. Default `locale`. */
+  storageKey?: string;
+}
+declare module '@kitr/core' {
+  interface ConfigRegistry {
+    i18n: I18nConfig;
+  }
+  interface ContainerBindings {
+    i18n: i18n;
+  }
+}
+/** Types `config/i18n.ts`. Returns the object you pass, unchanged. */
+export declare const defineConfig: <const C extends I18nConfig>(config: C) => C;
+/** Keys of a resource bundle as `namespace:key.path` strings, for typed `t()`. */
+export type TranslationKeys<R, Prefix extends string = ''> = { [K in keyof R & string]: R[K] extends string ? `${Prefix}${K}` : TranslationKeys<R[K], `${Prefix}${K}.`>; }[keyof R & string];
+/**
+ * Creates an isolated i18next instance from your config, already initialised with react-i18next.
+ * The locale is `initialLocale`, else the detected one when `detect` is on, else `defaultLocale`.
+ */
+export declare function createI18n(config: I18nConfig, initialLocale?: string): i18n;
+/**
+ * In the browser, the saved choice under `storageKey` in localStorage, else the best match for
+ * `navigator.languages`. Returns `undefined` on the server or when nothing matches.
+ */
+export declare function detectLocale(supported: string[], storageKey?: string): string | undefined;
+/** Pick the best supported locale from an `Accept-Language` header (server) or a language list. */
+export declare function matchLocale(candidates: string | readonly string[], supported: string[]): string | undefined;
+export { i18next };

package/dist/index.js

@@ -0,0 +1,56 @@
+import { createDefineConfig } from "@kitr/core";
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+export * from "react-i18next";
+// src/index.tsx
+/** Types `config/i18n.ts`. Returns the object you pass, unchanged. */
+const defineConfig = createDefineConfig();
+/**
+* Creates an isolated i18next instance from your config, already initialised with react-i18next.
+* The locale is `initialLocale`, else the detected one when `detect` is on, else `defaultLocale`.
+*/
+function createI18n(config, initialLocale) {
+	const { resources, defaultLocale, locales, detect = true, storageKey = "locale", ...rest } = config;
+	const supported = locales ?? Object.keys(resources);
+	const namespaces = [...new Set(Object.values(resources).flatMap((bundle) => Object.keys(bundle)))];
+	const defaultNS = namespaces.includes("common") ? "common" : namespaces[0];
+	const instance = i18next.createInstance();
+	const locale = initialLocale ?? (detect ? detectLocale(supported, storageKey) : void 0) ?? defaultLocale;
+	instance.use(initReactI18next).init({
+		resources,
+		lng: locale,
+		fallbackLng: defaultLocale,
+		supportedLngs: supported,
+		...defaultNS ? {
+			ns: namespaces,
+			defaultNS
+		} : {},
+		interpolation: { escapeValue: false },
+		react: { useSuspense: false },
+		...rest
+	});
+	return instance;
+}
+/**
+* In the browser, the saved choice under `storageKey` in localStorage, else the best match for
+* `navigator.languages`. Returns `undefined` on the server or when nothing matches.
+*/
+function detectLocale(supported, storageKey = "locale") {
+	if (typeof window === "undefined") return void 0;
+	try {
+		const stored = window.localStorage.getItem(storageKey);
+		if (stored && supported.includes(stored)) return stored;
+	} catch {}
+	return matchLocale(navigator.languages ?? [navigator.language], supported);
+}
+/** Pick the best supported locale from an `Accept-Language` header (server) or a language list. */
+function matchLocale(candidates, supported) {
+	const list = typeof candidates === "string" ? candidates.split(",").map((p) => p.trim().split(";")[0]).filter(Boolean) : candidates;
+	for (const lang of list) {
+		if (supported.includes(lang)) return lang;
+		const short = lang.split("-")[0];
+		const hit = supported.find((s) => s === short || s.startsWith(`${short}-`));
+		if (hit) return hit;
+	}
+}
+export { createI18n, defineConfig, detectLocale, i18next, matchLocale };

package/dist/kitr.d.ts

@@ -0,0 +1,17 @@
+/** `kitr add i18n`: react-i18next with typed keys, locale detection and a provider. */
+declare const _default: {
+  readonly name: "i18n";
+  readonly client: true;
+  readonly add: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly remove: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly wraps: {
+    readonly 'react-i18next': "@kitr/i18n";
+  };
+  readonly eject: {
+    readonly '@kitr/i18n': "react-i18next";
+  };
+  readonly vite: {
+    readonly optimizeDeps: ["i18next", "react-i18next"];
+  };
+};
+export { _default as default };

package/dist/kitr.js

@@ -0,0 +1,23 @@
+import { definePackage } from "@kitr/core/package";
+// src/kitr.ts
+/** `kitr add i18n`: react-i18next with typed keys, locale detection and a provider. */
+var kitr_default = definePackage({
+	name: "i18n",
+	client: true,
+	add(ctx) {
+		ctx.deps.add("i18next", "react-i18next");
+		ctx.provider.add("@kitr/i18n/provider");
+		ctx.write("app/locales/en.ts", `export default {\n  common: {\n    hello: 'Hello, {{name}}',\n    save: 'Save',\n  },\n} as const\n`);
+		ctx.config("i18n", `import { defineConfig } from '@kitr/i18n'\nimport en from '#app/locales/en'\n\nexport default defineConfig({\n  resources: { en },\n  defaultLocale: 'en',\n  defaultNS: 'common',\n})\n`);
+		ctx.agents.add("i18n", `- Strings live in \`app/locales/<lang>.ts\`. Components: \`const { t } = useTranslation()\` from \`@kitr/i18n\`; keys are typed from the English bundle.`);
+	},
+	remove(ctx) {
+		ctx.provider.remove("@kitr/i18n/provider");
+		ctx.deps.remove("i18next", "react-i18next");
+		ctx.agents.remove("i18n");
+	},
+	wraps: { "react-i18next": "@kitr/i18n" },
+	eject: { "@kitr/i18n": "react-i18next" },
+	vite: { optimizeDeps: ["i18next", "react-i18next"] }
+});
+export { kitr_default as default };

package/dist/provider.d.ts

@@ -0,0 +1,4 @@
+import { KitrProvider } from "@kitr/core";
+/** Binds `i18n` from `config/i18n.ts` and wraps the tree in I18nextProvider. */
+export declare const i18nProvider: KitrProvider;
+export { i18nProvider as default };

package/dist/provider.js

@@ -0,0 +1,19 @@
+import { createI18n } from "./index.js";
+import { defineProvider } from "@kitr/core";
+import { I18nextProvider } from "react-i18next";
+import { jsx } from "react/jsx-runtime";
+// src/provider.tsx
+/** Binds `i18n` from `config/i18n.ts` and wraps the tree in I18nextProvider. */
+const i18nProvider = defineProvider({
+	name: "i18n",
+	register(app) {
+		app.container.scoped("i18n", () => createI18n(app.config.get("i18n"), app.env.locale));
+	},
+	wrap(children, app) {
+		return /* @__PURE__ */ jsx(I18nextProvider, {
+			i18n: app.container.use("i18n"),
+			children
+		});
+	}
+});
+export { i18nProvider as default, i18nProvider };

package/docs/api.md

@@ -0,0 +1,89 @@
+---
+title: API reference
+description: Every export of @kitr/i18n, with its signature.
+order: 2
+---
+
+# API reference
+
+Every export of `@kitr/i18n`, `@kitr/i18n/provider`, read from the published type definitions. The [guide](/packages/i18n/guide) shows them in use.
+
+## @kitr/i18n
+
+Re-exports `i18next`, `react-i18next` unchanged, plus the following.
+
+### createI18n
+
+```ts
+function createI18n(config: I18nConfig, initialLocale?: string): i18n;
+```
+
+Creates an isolated i18next instance from your config, already initialised with react-i18next.
+The locale is `initialLocale`, else the detected one when `detect` is on, else `defaultLocale`.
+
+### detectLocale
+
+```ts
+function detectLocale(supported: string[], storageKey?: string): string | undefined;
+```
+
+In the browser, the saved choice under `storageKey` in localStorage, else the best match for
+`navigator.languages`. Returns `undefined` on the server or when nothing matches.
+
+### matchLocale
+
+```ts
+function matchLocale(candidates: string | readonly string[], supported: string[]): string | undefined;
+```
+
+Pick the best supported locale from an `Accept-Language` header (server) or a language list.
+
+### defineConfig
+
+```ts
+const defineConfig: <const C extends I18nConfig>(config: C) => C;
+```
+
+Types `config/i18n.ts`. Returns the object you pass, unchanged.
+
+### I18nConfig
+
+```ts
+interface I18nConfig extends Omit<InitOptions, 'resources' | 'lng'> {
+  /** Every locale's strings, keyed by locale then namespace: `{ en: { common: { hello: 'Hello' } } }`. */
+  resources: Record<string, Record<string, Record<string, unknown>>>;
+  /** The locale used when nothing better matches, and the fallback for missing keys. */
+  defaultLocale: string;
+  /** The locales the app supports. Default: the keys of `resources`. */
+  locales?: string[];
+  /** Detect from `navigator.language` (client) or `Accept-Language` (server). Default true. */
+  detect?: boolean;
+  /** Query/cookie/storage key for an explicit choice. Default `locale`. */
+  storageKey?: string;
+}
+```
+
+The options in `config/i18n.ts`: your strings per locale, the fallback locale and detection.
+Any other i18next init option passes straight through.
+
+### TranslationKeys
+
+```ts
+type TranslationKeys<R, Prefix extends string = ''> = {
+  [K in keyof R & string]: R[K] extends string ? `${Prefix}${K}` : TranslationKeys<R[K], `${Prefix}${K}.`>;
+}[keyof R & string];
+```
+
+Keys of a resource bundle as `namespace:key.path` strings, for typed `t()`.
+
+## @kitr/i18n/provider
+
+### i18nProvider
+
+```ts
+const i18nProvider: KitrProvider;
+```
+
+Binds `i18n` from `config/i18n.ts` and wraps the tree in I18nextProvider.
+
+<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->

package/docs/index.md

@@ -0,0 +1,605 @@
+---
+title: Translations
+description: Translate your app into several languages with typed keys.
+order: 1
+---
+
+# Translations
+
+Acme's first customers all read English. Then a team in Berlin signs up, and every button, empty state and order total needs to read naturally in German too. `@kitr/i18n` moves your interface text into one file per language, picks the visitor's language automatically, and makes a misspelled key a type error.
+
+> [!SUMMARY]
+> Translations with typed keys and automatic language detection, built on react-i18next. Add it with `kitr add i18n`; the overview is at [/packages/i18n](/packages/i18n).
+
+It is [react-i18next](https://react.i18next.com) and [i18next](https://www.i18next.com), re-exported unchanged, with a provider and sensible defaults: the fallback language is your default locale, there is no HTML escaping (React already escapes) and no Suspense. It adds `matchLocale()` for `Accept-Language` headers and a `TranslationKeys` type for typed key props.
+
+The provider runs in the browser, inside React. On the server you can still call `createI18n()` or `matchLocale()` directly, to translate an email or pick a page's language.
+
+The examples translate Acme's order screens at `app.acme.com` into English and German.
+
+## Install
+
+```sh
+kitr add i18n
+```
+
+<details>
+<summary>Everything kitr add changes</summary>
+
+What `kitr add` does:
+
+- Adds `@kitr/i18n`, `i18next` and `react-i18next` to `dependencies` and installs them. Pass `--no-install` to skip the install.
+- Adds `() => import('@kitr/i18n/provider')` to `providers` and `'@kitr/i18n'` to `packages` in `kitrrc.ts`. The provider binds `i18n` in the container and wraps your app in react-i18next's `I18nextProvider`.
+- Writes `app/locales/en.ts` with a `common` namespace holding `hello` and `save`, unless the file exists.
+- Writes `config/i18n.ts`, unless it exists. See [Configure](#configure).
+- Adds a `## kitr: i18n` section to `AGENTS.md`: strings live in `app/locales/<lang>.ts`, components call `const { t } = useTranslation()` from `@kitr/i18n`, and keys are typed from the English bundle.
+
+The `site` kit includes i18n with English and German bundles, a language switch, and the visitor's choice in a cookie so server-rendered pages arrive in the right language.
+
+`kitr remove i18n` takes the provider and the package out of `kitrrc.ts`, deletes `config/i18n.ts`, removes the three dependencies and the `AGENTS.md` section, then lists files that still import `@kitr/i18n`. It leaves `app/locales/` in place.
+
+</details>
+
+> [!WARNING] Client packages only
+> `kitr add i18n` skips a server-only project with a warning.
+
+## Configure
+
+`kitr add i18n` writes this file:
+
+```ts
+// config/i18n.ts
+import { defineConfig } from '@kitr/i18n'
+import en from '#app/locales/en'
+
+export default defineConfig({
+  resources: { en },
+  defaultLocale: 'en',
+  defaultNS: 'common',
+})
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `resources` | required | Every locale's strings, keyed by locale then namespace: `{ en: { common: { ... } } }`. |
+| `defaultLocale` | required | The language used when nothing better matches, and the fallback for any key missing in another language. |
+| `locales` | the keys of `resources` | The languages the app supports. A language outside this list is never chosen, even when you call `changeLanguage()` with it. |
+| `detect` | `true` | In the browser, choose the language from the saved choice under `storageKey`, then from the browser's languages. `false` always starts in `defaultLocale`. |
+| `storageKey` | `'locale'` | The `localStorage` key detection reads for a saved choice. |
+| `defaultNS` | `'common'` when a bundle has it, else the first namespace in `resources` | The namespace `t('save')` looks in when the key names none. |
+
+Any other [i18next option](https://www.i18next.com/overview/configuration-options) passes straight through, and wins over kitr's defaults:
+
+| i18next option | kitr's default | Why |
+| --- | --- | --- |
+| `fallbackLng` | `defaultLocale` | A German page with a missing key shows the English string, not the key. |
+| `supportedLngs` | `locales` | Only languages you ship are chosen. |
+| `interpolation.escapeValue` | `false` | React escapes text already; escaping twice shows `&lt;`. |
+| `react.useSuspense` | `false` | Bundles are in memory, so there is nothing to wait for. |
+
+> [!WARNING] interpolation replaces kitr's object
+> Include `escapeValue: false` in it when you add other interpolation options.
+
+## Translate your first string
+
+The generated `app/locales/en.ts` holds one namespace, `common`:
+
+```ts
+// app/locales/en.ts
+export default {
+  common: {
+    hello: 'Hello, {{name}}',
+    save: 'Save',
+  },
+} as const
+```
+
+In a component, `useTranslation()` from `@kitr/i18n` returns `t`, which looks a key up in the current language:
+
+```tsx
+// app/components/orders/welcome.tsx
+import { useTranslation } from '@kitr/i18n'
+
+export function Welcome({ name }: { name: string }) {
+  const { t } = useTranslation()
+  return (
+    <section>
+      <h2>{t('hello', { name })}</h2>
+      <button type="submit">{t('save')}</button>
+    </section>
+  )
+}
+```
+
+`<Welcome name="Ada" />` renders "Hello, Ada" and a "Save" button. `as const` keeps the exact strings, which [typed keys](#type-your-keys) need.
+
+## Organize strings into namespaces
+
+Each top-level key in a bundle is a namespace. Keep `common` for words used everywhere and give each feature its own:
+
+```ts
+// app/locales/en.ts
+export default {
+  common: {
+    hello: 'Hello, {{name}}',
+    save: 'Save',
+    cancel: 'Cancel',
+  },
+  orders: {
+    title: 'Orders',
+    empty: 'No orders yet',
+    status: { open: 'Open', paid: 'Paid', refunded: 'Refunded' },
+  },
+} as const
+```
+
+Pass a namespace to `useTranslation` to make it the default for that component. Reach another namespace with a `namespace:` prefix, and nested keys with dots:
+
+```tsx
+// app/components/orders/orders-header.tsx
+import { useTranslation } from '@kitr/i18n'
+
+export function OrdersHeader() {
+  const { t } = useTranslation('orders')
+  return (
+    <header>
+      <h1>{t('title')}</h1>
+      <span>{t('status.open')}</span>
+      <button type="button">{t('common:cancel')}</button>
+    </header>
+  )
+}
+```
+
+For one branch, `useTranslation('orders', { keyPrefix: 'status' })` lets you write `t('paid')` for `orders.status.paid`.
+
+## Insert values
+
+Put a placeholder in double braces and pass the value under the same name:
+
+```tsx
+// app/components/orders/assigned-to.tsx
+import { useTranslation } from '@kitr/i18n'
+
+export function AssignedTo({ order }: { order: { id: string; owner: string } }) {
+  const { t } = useTranslation('orders')
+  // orders.assigned: 'Order {{id}} is assigned to {{owner}}'
+  return <p>{t('assigned', { id: order.id, owner: order.owner })}</p>
+  // => Order 1001 is assigned to Grace
+}
+```
+
+> [!WARNING] Values are not HTML-escaped
+> Rendered as React text that is safe. Never pass a translated string to `dangerouslySetInnerHTML`; use [Trans](#put-markup-inside-a-string) for markup.
+
+## Count things
+
+Give a key one variant per plural form and pass `count`. i18next picks the form for the current language:
+
+```ts
+// app/locales/en.ts
+export default {
+  orders: {
+    count_zero: 'No orders',
+    count_one: '{{count}} order',
+    count_other: '{{count}} orders',
+  },
+} as const
+```
+
+```tsx
+// app/components/orders/order-count.tsx
+import { useTranslation } from '@kitr/i18n'
+
+export function OrderCount({ count }: { count: number }) {
+  const { t } = useTranslation('orders')
+  return <p>{t('count', { count })}</p>
+}
+// count 0 => No orders
+// count 1 => 1 order
+// count 3 => 3 orders
+```
+
+Ask for `count`, never `count_one`. `_zero` is optional. Other languages need other forms, such as Polish `_few` and `_many`; see the [i18next plural guide](https://www.i18next.com/translation-function/plurals).
+
+## Format numbers, money and dates
+
+Name a formatter after the value inside the braces. It uses `Intl` with the current language, so one key prints `€1,234.50` in English and `1.234,50 €` in German:
+
+```ts
+// app/locales/en.ts
+export default {
+  orders: {
+    total: 'Total: {{amount, currency(EUR)}}',
+    placed: 'Placed on {{date, datetime}}',
+    items: '{{count, number}} items',
+  },
+} as const
+```
+
+```tsx
+// app/components/orders/order-summary.tsx
+import { useTranslation } from '@kitr/i18n'
+
+export function OrderSummary({ order }: { order: { total: number; placedAt: Date } }) {
+  const { t } = useTranslation('orders')
+  return (
+    <dl>
+      <dd>{t('total', { amount: order.total })}</dd>
+      <dd>{t('placed', { date: order.placedAt })}</dd>
+    </dl>
+  )
+}
+// en, total 1234.5 => Total: €1,234.50
+// de, total 1234.5 => Summe: 1.234,50 €
+// de, placedAt 2026-03-01 => Bestellt am 1.3.2026
+```
+
+The formatters are `number`, `currency`, `datetime`, `relativetime` and `list`, each taking `Intl` options in parentheses; see [i18next formatting](https://www.i18next.com/translation-function/formatting). Pass raw numbers and `Date` objects to `t`; don't format them first.
+
+## Put markup inside a string
+
+A sentence with a link or bold words can't be split without breaking word order in other languages. Keep it as one string with named tags and render it with `Trans`:
+
+```ts
+// app/locales/en.ts
+export default {
+  common: {
+    welcome: 'Welcome back, <bold>{{name}}</bold>. <link>See your orders</link>.',
+  },
+} as const
+```
+
+```tsx
+// app/components/orders/welcome-back.tsx
+import { Trans } from '@kitr/i18n'
+
+export function WelcomeBack({ name }: { name: string }) {
+  return (
+    <p>
+      <Trans
+        i18nKey="common:welcome"
+        values={{ name }}
+        components={{ bold: <strong />, link: <a href="https://app.acme.com/orders" /> }}
+      />
+    </p>
+  )
+}
+```
+
+The German bundle can move the tags anywhere in its sentence. [Trans in react-i18next's docs](https://react.i18next.com/latest/trans-component) covers the other forms.
+
+## Add a language
+
+Copy the English bundle, translate it, and list it in the config. Typing the copy against the English one makes a missing key fail the type check:
+
+```ts
+// app/locales/en.ts
+const en = {
+  common: { hello: 'Hello, {{name}}', save: 'Save' },
+  orders: { title: 'Orders', empty: 'No orders yet' },
+} as const
+
+export default en
+
+/** The shape every other locale must match: same keys, any strings. */
+export type Bundle<T> = { [K in keyof T]: T[K] extends string ? string : Bundle<T[K]> }
+```
+
+```ts
+// app/locales/de.ts
+import type { Bundle } from './en'
+import type en from './en'
+
+const de = {
+  common: { hello: 'Hallo, {{name}}', save: 'Speichern' },
+  orders: { title: 'Bestellungen', empty: 'Noch keine Bestellungen' },
+} as const satisfies Bundle<typeof en>
+
+export default de
+```
+
+```ts
+// config/i18n.ts
+import { defineConfig } from '@kitr/i18n'
+import de from '#app/locales/de'
+import en from '#app/locales/en'
+
+export default defineConfig({
+  resources: { en, de },
+  defaultLocale: 'en',
+  defaultNS: 'common',
+})
+```
+
+A key missing from `de.ts` is a type error, and at run time a German page shows the English string. Plural keys are the exception: a language may need forms English lacks, so loosen `Bundle` for those namespaces.
+
+## Type your keys
+
+Tell i18next the shape of the English bundle once, and `t()` autocompletes every key and rejects typos at compile time:
+
+```ts
+// app/i18n.d.ts
+import type en from '#app/locales/en'
+
+declare module 'i18next' {
+  interface CustomTypeOptions {
+    defaultNS: 'common'
+    resources: typeof en
+  }
+}
+```
+
+```tsx
+// app/components/orders/orders-header.tsx
+import { useTranslation } from '@kitr/i18n'
+
+export function OrdersHeader() {
+  const { t } = useTranslation('orders')
+  return <h1>{t('titel')}</h1>
+  // Type error: 'titel' is not a key of the orders namespace
+}
+```
+
+When a component takes a key as a prop, type it with `TranslationKeys`, which flattens a namespace into dotted key paths:
+
+```tsx
+// app/components/orders/status-badge.tsx
+import { type TranslationKeys, useTranslation } from '@kitr/i18n'
+import type en from '#app/locales/en'
+
+type OrderKey = TranslationKeys<(typeof en)['orders']>
+// => 'title' | 'empty' | 'status.open' | 'status.paid' | 'status.refunded'
+
+export function StatusBadge({ label }: { label: OrderKey }) {
+  const { t } = useTranslation('orders')
+  return <span className="badge">{t(label)}</span>
+}
+```
+
+> [!WARNING] Pass one namespace
+> `TranslationKeys<typeof en>` over the whole bundle gives `'common.hello'`, not the `common:hello` form `t()` expects.
+
+## Switch the language
+
+`i18n.changeLanguage()` switches every mounted component. Save the choice under `storageKey` so detection finds it next visit:
+
+```tsx
+// app/components/language-switch.tsx
+import { useTranslation } from '@kitr/i18n'
+
+const languages = { en: 'English', de: 'Deutsch' } as const
+
+export function LanguageSwitch() {
+  const { i18n } = useTranslation()
+  return (
+    <select
+      value={i18n.resolvedLanguage}
+      onChange={(event) => {
+        const next = event.target.value
+        localStorage.setItem('locale', next)
+        void i18n.changeLanguage(next)
+      }}
+    >
+      {Object.entries(languages).map(([code, label]) => (
+        <option key={code} value={code}>
+          {label}
+        </option>
+      ))}
+    </select>
+  )
+}
+```
+
+`changeLanguage` writes neither `localStorage` nor `<html lang>`. Keep `<html lang>` in sync for screen readers by listening once at startup:
+
+```ts
+// app/client.tsx
+import { app } from './app'
+
+app.boot().then(() => {
+  const i18n = app.container.use('i18n')
+  document.documentElement.lang = i18n.language
+  i18n.on('languageChanged', (language) => {
+    document.documentElement.lang = language
+  })
+  // ... then hydrate or render as before
+})
+```
+
+A language outside `locales` is never chosen: `changeLanguage('fr')` without a French bundle stays on `en`.
+
+## Detect the visitor's language
+
+With `detect: true`, the provider picks the first language in this order:
+
+1. `app.env.locale`, when the app was created with one.
+2. The saved choice in `localStorage` under `storageKey`, when it is a supported language.
+3. The browser's `navigator.languages`, matched against your languages.
+4. `defaultLocale`.
+
+Matching tries each browser language in order: an exact match wins, then the base language (`en-GB` matches `en`), and a base matches a regional bundle (`pt` matches `pt-BR`). `detectLocale(supported, storageKey)` runs steps 2 and 3 alone:
+
+```ts
+// app/lib/settings/language.ts
+import { detectLocale } from '@kitr/i18n'
+
+detectLocale(['en', 'de'])
+// navigator.languages ['de-AT', 'en'] and nothing saved => 'de'
+// localStorage locale = 'en' => 'en'
+// on the server => undefined
+```
+
+Detection runs once at startup. Use `detect: false` when the server decides the language.
+
+## Choose the language on the server
+
+On the server the `Accept-Language` header carries the visitor's preference. `matchLocale()` parses it and returns the best supported language:
+
+```ts
+// server/controllers/locale-controller.ts
+import type { HttpContext } from '@kitr/api'
+import { matchLocale } from '@kitr/i18n'
+
+export default class LocaleController {
+  async show({ request }: HttpContext) {
+    const header = request.header('accept-language') ?? ''
+    return { locale: matchLocale(header, ['en', 'de']) ?? 'en' }
+  }
+}
+```
+
+With `['en', 'de']` supported:
+
+| `Accept-Language` | Result |
+| --- | --- |
+| `de-CH,de;q=0.9,en;q=0.8` | `'de'` |
+| `en-GB` | `'en'` |
+| `fr-FR,fr;q=0.9` | `undefined` |
+| `''` | `undefined` |
+
+It reads languages in header order and does not sort by `q`; browsers already send them in preference order. It also takes an array such as `navigator.languages`. A server-rendered app usually stores the choice in a cookie so server and browser agree; the `site` kit does this with [storage](/packages/storage)'s `defineCookie`.
+
+## Translate outside components
+
+The provider binds the instance as `i18n` in the container. Read it where there are no hooks, such as a toast after a mutation:
+
+```ts
+// app/lib/orders/notify.ts
+import type { KitrApp } from 'kitr/app'
+
+export function orderSavedMessage(app: KitrApp, orderId: string) {
+  const i18n = app.container.use('i18n')
+  return i18n.t('orders:saved', { id: orderId })
+  // en => Order 1001 saved
+}
+```
+
+For an email in the customer's language, create an instance from the same config and take a fixed `t` per language:
+
+```ts
+// server/mail/order-confirmation.ts
+import { createI18n } from '@kitr/i18n'
+import i18nConfig from '#config/i18n'
+
+const i18n = createI18n({ ...i18nConfig, detect: false })
+
+export function confirmationSubject(locale: string, count: number) {
+  const t = i18n.getFixedT(locale, 'orders')
+  return t('count', { count })
+}
+// confirmationSubject('de', 2) => 2 Bestellungen
+```
+
+> [!WARNING] Don't change language on a shared instance
+> An instance you create at module level is shared by every request, so `changeLanguage()` would switch the language under requests still rendering. Use `getFixedT`, or `i18n.cloneInstance({ lng })` for a per-request copy.
+
+## Load a language on demand
+
+Every bundle in `resources` ships in the main JavaScript bundle. Load rarely used languages when chosen, and list them in `locales` up front:
+
+```ts
+// app/lib/settings/load-language.ts
+import type { KitrApp } from 'kitr/app'
+
+export async function useFrench(app: KitrApp) {
+  const i18n = app.container.use('i18n')
+  const { default: fr } = await import('#app/locales/fr')
+  for (const [namespace, strings] of Object.entries(fr)) {
+    i18n.addResourceBundle('fr', namespace, strings)
+  }
+  await i18n.changeLanguage('fr')
+}
+```
+
+```ts
+// config/i18n.ts
+import { defineConfig } from '@kitr/i18n'
+import de from '#app/locales/de'
+import en from '#app/locales/en'
+
+export default defineConfig({
+  resources: { en, de },
+  locales: ['en', 'de', 'fr'],
+  defaultLocale: 'en',
+  defaultNS: 'common',
+})
+```
+
+Without `fr` in `locales`, `changeLanguage('fr')` stays on English. To load every language over HTTP, see i18next [backend plugins](https://www.i18next.com/overview/plugins-and-utils#backends).
+
+## Handle missing keys
+
+A key missing in German shows the English string. A key that exists nowhere shows the key itself, without its namespace:
+
+```ts
+// app/lib/orders/missing.ts
+import type { KitrApp } from 'kitr/app'
+
+export function demo(app: KitrApp) {
+  const i18n = app.container.use('i18n')
+  i18n.t('orders:refundNote')
+  // => 'refundNote' when no bundle has it
+}
+```
+
+Typed keys catch this at compile time. To report missing keys at run time, pass i18next's `saveMissing` and `missingKeyHandler` in `config/i18n.ts`.
+
+## Testing
+
+Render translated components with [testing](/packages/testing)'s `createTestApp` and `renderWithKitr`. Use `detect: false` so the runner's browser language doesn't decide the result, and `env: { locale }` to render another language:
+
+```tsx
+// app/components/orders/orders-header.test.tsx
+import { screen } from '@testing-library/react'
+import { useTranslation } from '@kitr/i18n'
+import i18nProvider from '@kitr/i18n/provider'
+import { createTestApp } from '@kitr/testing'
+import { renderWithKitr } from '@kitr/testing/react'
+import { describe, expect, it } from 'vitest'
+import i18nConfig from '#config/i18n'
+
+function OrdersHeader({ count, total }: { count: number; total: number }) {
+  const { t } = useTranslation('orders')
+  return (
+    <header>
+      <h1>{t('title')}</h1>
+      <p>{t('count', { count })}</p>
+      <p>{t('total', { amount: total })}</p>
+    </header>
+  )
+}
+
+const boot = (locale?: string) =>
+  createTestApp({
+    providers: [i18nProvider],
+    config: { i18n: { ...i18nConfig, detect: false } },
+    env: locale ? { locale } : {},
+  })
+
+describe('OrdersHeader', () => {
+  it('renders in English by default', async () => {
+    renderWithKitr(<OrdersHeader count={3} total={1234.5} />, { app: await boot() })
+
+    expect(screen.getByRole('heading', { name: 'Orders' })).toBeTruthy()
+    expect(screen.getByText('3 orders')).toBeTruthy()
+    expect(screen.getByText('Total: €1,234.50')).toBeTruthy()
+  })
+
+  it('renders in German', async () => {
+    renderWithKitr(<OrdersHeader count={1} total={1234.5} />, { app: await boot('de') })
+
+    expect(screen.getByRole('heading', { name: 'Bestellungen' })).toBeTruthy()
+    expect(screen.getByText('1 Bestellung')).toBeTruthy()
+    expect(screen.getByText('Summe: 1.234,50 €')).toBeTruthy()
+  })
+})
+```
+
+To test plain functions that call `t`, skip React and use `createI18n(i18nConfig, 'de').t(...)`.
+
+## Next steps
+
+- [API reference](/packages/i18n/api): every export of `@kitr/i18n` and `@kitr/i18n/provider`.
+- [Storage](/packages/storage): keep the visitor's language in a cookie the server can read.
+- [i18next docs](https://www.i18next.com): plurals, formatting, context and options.

package/docs/overview.md

@@ -0,0 +1,74 @@
+---
+title: Overview
+description: Translate your app into several languages with typed keys.
+order: 0
+---
+
+# Translations
+
+## What it is
+
+`@kitr/i18n` is react-i18next with typed keys. Strings live in one file per language under `app/locales/`, components call `t('key')`, and a misspelt key is a type error. The provider picks the visitor's language from a saved choice or the browser.
+
+Runs in the browser. On the server, `matchLocale()` picks a language from `Accept-Language`.
+
+## Install
+
+```sh
+kitr add i18n
+```
+
+Adds `@kitr/i18n` with i18next and react-i18next, its provider, `config/i18n.ts` and `app/locales/en.ts`. [Every change](/packages/i18n/guide#install).
+
+## Quick start
+
+The generated English bundle holds one namespace:
+
+```ts
+// app/locales/en.ts
+export default {
+  common: {
+    hello: 'Hello, {{name}}',
+    save: 'Save',
+  },
+} as const
+```
+
+In a component, `useTranslation()` returns `t`, which looks a key up in the current language:
+
+```tsx
+// app/features/orders/welcome.tsx
+import { useTranslation } from '@kitr/i18n'
+
+export function Welcome({ name }: { name: string }) {
+  const { t } = useTranslation()
+  return (
+    <section>
+      <h2>{t('hello', { name })}</h2>
+      <button type="submit">{t('save')}</button>
+    </section>
+  )
+}
+```
+
+`<Welcome name="Ada" />` renders "Hello, Ada" and a "Save" button. `t('helo')` is a type error. Next in the guide: [Translate your first string](/packages/i18n/guide#translate-your-first-string).
+
+## Built on
+
+kitr adds the provider with sensible defaults, `matchLocale()` for the server, `detectLocale()` for the client and the `TranslationKeys` type.
+
+## Problems it solves
+
+- **Strings scattered through components.** [Organize strings into namespaces](/packages/i18n/guide#organize-strings-into-namespaces).
+- **Plurals and formatting done by hand.** [Count things](/packages/i18n/guide#count-things).
+- **Misspelt keys that render blank.** [Type your keys](/packages/i18n/guide#type-your-keys).
+- **The wrong language on first render.** [Choose the language on the server](/packages/i18n/guide#choose-the-language-on-the-server).
+- **Every language shipped to every visitor.** [Load a language on demand](/packages/i18n/guide#load-a-language-on-demand).
+
+## Further reading
+
+- [Guide](/packages/i18n/guide).
+- [API reference](/packages/i18n/api).
+- [react-i18next docs](https://react.i18next.com).
+- [i18next docs](https://www.i18next.com).
+- [Storage](/packages/storage).

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@kitr/i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "@kitr/i18n: react-i18next re-exported, plus typed keys and locale helpers.",
+  "kitr": {
+    "name": "i18n",
+    "title": "Translations",
+    "summary": "Translate your app into several languages with typed keys.",
+    "category": "interface",
+    "runsOn": "client",
+    "builtOn": [
+      "react-i18next"
+    ],
+    "client": true,
+    "docs": "docs",
+    "setup": "./kitr"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitrjs/kitr.git",
+    "directory": "packages/i18n"
+  },
+  "homepage": "https://kitr.dev/packages/i18n",
+  "bugs": "https://github.com/kitrjs/kitr/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "default": "./dist/provider.js"
+    },
+    "./kitr": {
+      "types": "./dist/kitr.d.ts",
+      "default": "./dist/kitr.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "dependencies": {
+    "@kitr/core": "0.2.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "i18next": ">=23.0.0",
+    "react-i18next": ">=15.0.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.7",
+    "typescript": "^5.9.3",
+    "react": "^19.3.1",
+    "@types/react": "^19.3.0",
+    "i18next": "^27.0.0",
+    "react-i18next": "^18.0.0",
+    "@kitr/react": "0.2.1"
+  },
+  "keywords": [
+    "kitr",
+    "kitr-package"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }