kotori 6.0.0 → 6.1.0

package/README.md

@@ -11,7 +11,7 @@
 </p>
 
 <p align="center">
-🕊️ Kotori is a zero-config, fully type-safe, and modular internationalization library for React that compiles down to just 0.28kB. No JSON, no external CLI tools, no codegen—just live type inference from your strings.
+🕊️ Kotori is a zero-config, fully type-safe, and modular internationalization library for React that compiles down to just 0.29kB. No JSON, no external CLI tools, no codegen—just live type inference from your strings.
 </p>
 
 ```ts
@@ -55,13 +55,13 @@ const Component = () => {
 - No JSON
 - No dependencies
 - No build step
-- 0.28kB minified and gzipped
+- 0.29kB minified and gzipped
 - Modular and tree-shakeable
 - Language change in one page rerenders all pages
 - Variables typed and inferred from string literals — no more string typos
-- maximum type safety with minimum types
+- Maximum type safety with minimum types
 
-Demo: <https://stackblitz.com/edit/vitejs-vite-nyxwmhre?file=src%2FApp.tsx>
+Demo: <https://stackblitz.com/edit/kotori?file=src%2FApp.tsx>
 
 ## Installation
 
@@ -163,7 +163,7 @@ export const Page2 = () => {
 
 ![how kotori works](image.webp) 
 
-### `kotori(options)`
+### `kotori(options)` (0.29kB)
 
 Creates a scoped i18n instance.
 
@@ -178,14 +178,14 @@ export const { useT, d, setLanguage } = kotori({
 
 | option | type | description |
 | --- | --- | --- |
-| `primary` | `BCP47LanguageTag` | The source language. Drives variable inference. |
-| `secondaries` | `BCP47LanguageTag[]` | Additional supported languages. |
+| `primary` | `BCP47LanguageTagWithSubtag` | The source language. Drives variable inference. |
+| `secondaries` | `Exclude<BCP47LanguageTagWithSubtag, primary>[]` | Additional supported languages. Cannot include the primary language. |
 
 Returns `{ d, useT, setLanguage, r }`.
 
 ### `d(translations)<argsType?>`
 
-Defines a translation unit. Takes one string per language. Return `dictionary` object.
+Defines a translation unit. Takes one string per language. Returns a `dictionary` object.
 
 ```ts
 const time = d({ en: '{{hour}}:{{minute}}' })
@@ -215,7 +215,7 @@ Returns the translated string for the current language. `args` is required if th
 ⚠️ Do not call this inside React components (it will break React Compiler optimization rules). Use this exclusively in raw JS/TS environments like router guards, API interceptors, or state utilities.
 
 ```tsx
-r(intro, { name: 'John', age: 30 })}
+r(intro, { name: 'John', age: 30 })
 ```
 
 ### `useT()`
@@ -233,22 +233,69 @@ Returns the translated string for the current language. `args` is required if th
 React version of `r(dictionary, args?)`, works with React Compiler.
 
 ```tsx
-<p>{t(intro, { name: 'John', age: 30 })}</p>
+const Intro = () => {
+    const { t } = useT()
+
+    return (
+        <p>{t(intro, { name: 'John', age: 30 })}</p>
+    )
+}
+```
+
+### `detectLanguage(instance, options?)` (0.12kB with Kotori or 0.2kB standalone)
+
+Detects the user's preferred language from browser settings and sets it on the kotori instance. Iterates through the user's full language preference list in order, stopping at the first match.
+
+```ts
+import { detectLanguage } from 'kotori'
+import { i18n } from './locales'
+
+detectLanguage(i18n)
+```
+
+| option | type | default | description |
+| --- | --- | --- | --- |
+| `fallbackToSubtag` | `boolean` | `true` | If no exact match is found (e.g. `'zh-CN'`), fall back to the subtag (e.g. `'zh'`). |
+
+```ts
+// browser reports: ['zh-CN', 'en-US']
+// declared languages: ['en', 'zh', 'ja', 'ms']
+
+detectLanguage(i18n)
+// 'zh-CN' → no exact match → subtag 'zh' → match → setLanguage('zh') ✅
+
+detectLanguage(i18n, { fallbackToSubtag: false })
+// 'zh-CN' → no exact match → 'en-US' → no exact match → no-op, stays 'en'
+```
+
+`detectLanguage` also works with non-kotori instances. Any object with a `setLanguage` callback and a `config` object satisfies the interface:
+
+```ts
+detectLanguage({
+    setLanguage: (lang: 'en' | 'zh') => mySetLang(lang),
+    config: { primary: 'en', secondaries: ['zh'] },
+})
 ```
 
 ## Language Tags
 
-kotori uses [BCP 47](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) language tags. Both subtags (`en`, `zh`) and full tags (`en-US`, `zh-CN`) are accepted and validated at the type level.
+kotori uses [BCP 47](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) language tags. The type `BCP47LanguageTagWithSubtag` accepts both subtags (`en`, `zh`) and full tags (`en-US`, `zh-CN`), and is validated at the type level.
+
+```ts
+kotori({ primary: 'en', secondaries: ['zh', 'ms-MY'] })  // ✅
+kotori({ primary: 'klingon', secondaries: ['zh'] })       // ❌ compile error
+```
 
 ## Tips
 
 - If you plan to add new languages frequently, consider colocating all your dicts in a single file or multiple files in one folder. It is easier to copy the entire file and hand it to an AI to translate.
-- If your supported languages are fixed, consider splitting dicts by page or component. Translations stay close to the code that uses them and are easier to maintain.  
+- If your supported languages are fixed, consider splitting dicts by page or component. Translations stay close to the code that uses them and are easier to maintain. This approach also pairs well with TypeScript — every time you add a new language, type errors will guide you to every dict that needs updating.
 - Both approaches are tree-shakeable — only the dicts imported by the current page are included in its bundle.
+- The `primary` language is the source of truth for variable inference and validation. Write your primary language strings carefully — a variable rename in the primary string becomes a compile error across every secondary language, which is intentional.
 
 ## Roadmap
 
-- Auto detect locale from browser settings
+- ✅ Auto detect locale from browser settings
 - Auto persist language selection to localStorage
 - Pluralization support
 - Gender support
@@ -258,4 +305,4 @@ kotori uses [BCP 47](https://www.iana.org/assignments/language-subtag-registry/l
 
 There are already many i18n libraries, and the good names are mostly taken. The original plan was *kotoba* (言葉), the Japanese word for "words" — also taken. Claude suggested *kotori* as an alternative, and it stuck.
 
-*Kotori* (小鳥) means "small bird" in Japanese. No deeper relevance to the library — it just sounds nice.
+*Kotori* (小鳥) means "small bird" in Japanese. No deeper relevance to the library — it just sounds nice.

package/dist/index.cjs

@@ -1,13 +1,145 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let react = require("react");
-//#region src/index.ts
-const kotori = (props) => {
+//#region src/detectLanguage.ts
+/**
+* Detects the user's preferred language from browser settings and sets it
+* on the kotori instance. Iterates through the user's full language preference
+* list in order, stopping at the first match.
+*
+* @param instance - An object with `setLanguage` and `config`. Compatible with
+* the kotori instance returned by `kotori()`, or any custom object that satisfies
+* the same shape — allowing use with non-kotori setups.
+* @param instance.setLanguage - `(language: BCP47LanguageTagNameWithSubTag) => void` — Called with the
+* first matched language. Can be any callback — a kotori `setLanguage`, a React
+* state setter, a Zustand action, etc.
+* @param instance.config - Language configuration.
+* @param instance.config.primary - `BCP47LanguageTagNameWithSubTag` — The primary/fallback language tag.
+* @param instance.config.secondaries - `Exclude<AllTags, primary>[]` — Additional supported language tags. Cannot include the primary language.
+* @param options - Detection options.
+* @param options.fallbackToSubtag - `boolean` — If no exact match is found (e.g. `'zh-CN'`),
+* fall back to the subtag (e.g. `'zh'`). Defaults to `true`.
+* @returns `void` — Calls `setLanguage` on the first match. No-op if no match is found.
+*
+* @example
+* ```ts
+* // with kotori instance
+* import { kotori, detectLanguage } from 'kotori'
+*
+* const i18n = kotori({
+*   primary: 'en',
+*   secondaries: ['zh', 'ja', 'ms'],
+* })
+*
+* detectLanguage(i18n)
+* // browser: ['zh-CN', 'en-US'] → subtag 'zh' → setLanguage('zh') ✅
+*
+* detectLanguage(i18n, { fallbackToSubtag: false })
+* // browser: ['zh-CN'] → no exact match → no-op, stays 'en'
+* ```
+*
+* @example
+* ```ts
+* // ✅ setLanguage type exactly matches primary + secondaries union
+* detectLanguage({
+*   setLanguage: (lang: 'en' | 'zh' | 'ja') => setLang(lang),
+*   config: {
+*     primary: 'en',
+*     secondaries: ['zh', 'ja'],
+*   },
+* })
+*
+* // ❌ compile error — setLanguage accepts wider type than declared
+* detectLanguage({
+*   setLanguage: (lang: string) => setLang(lang),
+*   config: { primary: 'en', secondaries: ['zh'] },
+* })
+* ```
+*/
+const detectLanguage = (instance, options = { fallbackToSubtag: true }) => {
+	const languages = [instance.config.primary, ...instance.config.secondaries];
+	for (const browserLang of navigator.languages) {
+		if (languages.includes(browserLang)) return instance.setLanguage(browserLang);
+		if (options.fallbackToSubtag) {
+			const subtag = browserLang.split("-")[0];
+			if (languages.includes(subtag)) return instance.setLanguage(subtag);
+		}
+	}
+};
+//#endregion
+//#region src/kotori.ts
+/**
+* Creates a scoped i18n instance for your app.
+* Call once and export the returned utilities.
+*
+* @param config - Configuration options.
+* @param config.primary - `BCP47LanguageTag` — The source language. Variable inference and
+* secondary string validation are both driven by this language's strings.
+* @param config.secondaries - `Exclude<BCP47LanguageTag, primary>[]` — Additional supported languages.
+* Cannot include the primary language.
+* @returns `{ d, r, useT, setLanguage, config }`
+*
+* @example
+* ```ts
+* // locales.ts
+* import { kotori } from 'kotori'
+*
+* export const { d, r, useT, setLanguage } = kotori({
+*   primary: 'en',
+*   secondaries: ['zh', 'ja', 'ms'],
+* })
+* ```
+*/
+const kotori = (config) => {
 	const listeners = /* @__PURE__ */ new Set();
+	/**
+	* Translates a dict to the current language and interpolates variables.
+	*
+	* @param dictionary - A dict created by `d()`.
+	* @param args - `Record<string, string | number>` — Variable values to interpolate. Required if the dict has variables, omitted if it doesn't.
+	* @returns `string` — The translated and interpolated string.
+	*
+	* @example
+	* const Intro = () => {
+	*     const { t } = useT()
+	*
+	*     return (
+	*         <p>{t(greeting)}</p>                             // ✅ no args needed
+	*         <p>{t(intro, { name: 'John', age: 30 })}</p>     // ✅ typed args
+	*         <p>{t(intro)}</p>                                // ❌ compile error: missing args
+	*         <p>{t(intro, { name: 'John', x: 30 })}</p>       // ❌ compile error: unknown key 'x'
+	*     )
+	* }
+	*/
 	const t = (dictionary, ...args) => (dictionary().d[snapshot.language] || "").replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, key) => String(args[0]?.[key]));
 	let snapshot = {
-		language: props.primary,
+		language: config.primary,
 		t
 	};
+	/**
+	* Updates the current language and triggers a rerender in all active
+	* `useT()` consumers across all pages. Safe to call outside React.
+	*
+	* @param language - `Language` — Must be one of the tags declared in
+	* `primary` or `secondaries`. Any other value is a compile error.
+	* @returns `void`
+	*
+	* @example
+	* ```ts
+	* import { setLanguage } from './locales'
+	*
+	* setLanguage('zh')      // ✅
+	* setLanguage('ms')      // ✅
+	* setLanguage('de')      // ❌ compile error: 'de' was not declared
+	*
+	* // persist and restore language selection
+	* setLanguage('zh')
+	* localStorage.setItem('lang', 'zh')
+	*
+	* // restore on app startup
+	* const saved = localStorage.getItem('lang')
+	* if (saved) setLanguage(saved as 'en')
+	* ```
+	*/
 	const setLanguage = (language) => {
 		snapshot = {
 			language,
@@ -24,11 +156,130 @@ const kotori = (props) => {
 		};
 	};
 	return {
+		config,
 		setLanguage,
+		/**
+		* Translates a dict to the current language and interpolates variables.
+		* For use **outside** React components — route guards, axios interceptors,
+		* utility functions, etc.
+		*
+		* ⚠️ Do not use inside React components. The React Compiler will memoize
+		* the result permanently since `r` is a stable module-level reference,
+		* causing stale translations after a language change. Use `t` from `useT()`
+		* inside components instead.
+		*
+		* @param dictionary - A dict created by `d()`.
+		* @param args - `Record<string, string | number>` — Variable values to interpolate.
+		* Required if the dict has variables, omitted if it doesn't.
+		* @returns `string` — The translated and interpolated string in the current language.
+		*
+		* @example
+		* ```ts
+		* import { r, greeting, intro } from './locales'
+		*
+		* r(greeting)                          // ✅ no args needed
+		* r(intro, { name: 'John', age: 30 })  // ✅ typed args
+		* r(intro)                             // ❌ compile error: missing args
+		* r(intro, { name: 'John', x: 1 })     // ❌ compile error: unknown key 'x'
+		*
+		* // route guard
+		* router.beforeEach(() => {
+		*   document.title = r(pageTitle)
+		* })
+		*
+		* // axios interceptor
+		* axios.interceptors.response.use(null, () => {
+		*   toast.error(r(errorMessage))
+		* })
+		* ```
+		*/
 		r: t,
+		/**
+		* Defines a translation unit. The primary language string drives variable
+		* inference — all secondary strings are validated against it at compile time.
+		*
+		* Call with an optional generic to narrow variable types beyond the default
+		* `string | number`. Supports TypeScript template literal types.
+		*
+		* @param dictionary - `Record<Language, string>` — One string per language.
+		* Variables are declared with `{{variableName}}` syntax. Spaces inside braces
+		* are trimmed — `{{ name }}` and `{{name}}` are equivalent.
+		* Secondary strings must use exactly the same variable names as the primary.
+		* @returns A function optionally accepting a generic to narrow variable types,
+		* which returns the translation unit.
+		*
+		* @example
+		* ```ts
+		* // no variables
+		* const greeting = d({ en: 'Hello', zh: '你好', ja: 'こんにちは', ms: 'Helo' })()
+		*
+		* // variables — inferred as Record<'name' | 'age', string | number> by default
+		* const intro = d({
+		*   en: 'My name is {{name}}, I am {{age}} years old.',
+		*   zh: '我叫{{name}}，我今年{{age}}岁了。',
+		*   ja: '私の名前は{{name}}で、{{age}}歳です。',
+		*   ms: 'Nama saya {{name}}, saya berumur {{age}} tahun.',
+		* })()
+		*
+		* // narrowed variable types via generic
+		* const clock = d({
+		*   en: 'Current time: {{hour}}:{{minute}}',
+		*   zh: '现在时间：{{hour}}:{{minute}}',
+		*   ja: '現在時刻：{{hour}}:{{minute}}',
+		*   ms: 'Masa semasa: {{hour}}:{{minute}}',
+		* })<{ hour: number; minute: number }>()
+		*
+		* // TypeScript template literal types work too
+		* const lastLogin = d({
+		*   en: 'Last login: {{date}}',
+		*   zh: '上次登录：{{date}}',
+		*   ja: '最終ログイン：{{date}}',
+		*   ms: 'Log masuk terakhir: {{date}}',
+		* })<{ date: `${number}-${number}-${number}` }>()
+		*
+		* // ❌ compile error — 'ja' translation missing
+		* const bad1 = d({ en: 'Hello', zh: '你好', ms: 'Helo' })()
+		*
+		* // ❌ compile error — secondary string has wrong variable name
+		* const bad2 = d({ en: 'Hello {{name}}', zh: '你好 {{naam}}', ja: 'こんにちは {{name}}', ms: 'Helo {{name}}' })()
+		*
+		* // ❌ compile error — secondary string missing a variable
+		* const bad3 = d({ en: '{{x}} {{y}}', zh: '{{x}}', ja: '{{x}} {{y}}', ms: '{{x}} {{y}}' })()
+		* ```
+		*/
 		d: (dictionary) => () => ({ d: dictionary }),
+		/**
+		* React hook. Subscribes the component to language changes.
+		* Returns a snapshot containing the current `language` and a
+		* React Compiler-safe `t` function.
+		*
+		* Call in every component that renders translated strings.
+		* When `setLanguage` is called anywhere, all `useT()` consumers rerender.
+		*
+		* @returns `{ language: Language, t: TranslateFunction }`
+		* @returns `language` - `Language` — The current active language tag as a reactive value.
+		* @returns `t` - `TranslateFunction` — React Compiler-safe translate function. Use this inside components instead of the instance-level `t`.
+		*
+		* @example
+		* ```tsx
+		* import { useT, intro, time } from './locales'
+		*
+		* const Page = () => {
+		*   const { t, language } = useT()
+		*
+		*   return (
+		*     <>
+		*       <p>{t(intro, { name: 'John', age: 30 })}</p>
+		*       <p>{t(time, { hour: 12, minute: 0 })}</p>
+		*       <p>Current language: {language}</p>
+		*     </>
+		*   )
+		* }
+		* ```
+		*/
 		useT: () => (0, react.useSyncExternalStore)(subscribe, () => snapshot, () => snapshot)
 	};
 };
 //#endregion
+exports.detectLanguage = detectLanguage;
 exports.kotori = kotori;

package/dist/index.d.cts

@@ -1,26 +1,169 @@
 //#region node_modules/bcp47-language-tags/dist/zh.d.ts
 type BCP47LanguageTagName = "zh-CN" | "zh-TW" | "zh-HK" | "zh-MO" | "zh-SG" | "zh-CHS" | "zh-CHT" | "en-US" | "en-GB" | "en-CA" | "en-AU" | "en-IN" | "en-ZA" | "en-NZ" | "en-IE" | "en-PH" | "en-ZW" | "en-BZ" | "en-CB" | "en-JM" | "en-TT" | "hi-IN" | "es-ES" | "es-MX" | "es-AR" | "es-CO" | "es-PE" | "es-VE" | "es-CL" | "es-EC" | "es-GT" | "es-CU" | "es-BO" | "es-DO" | "es-HN" | "es-PY" | "es-SV" | "es-NI" | "es-PR" | "es-UY" | "es-PA" | "es-CR" | "ar-EG" | "ar-SA" | "ar-DZ" | "ar-MA" | "ar-IQ" | "ar-SD" | "ar-YE" | "ar-SY" | "ar-TN" | "ar-LY" | "ar-JO" | "ar-LB" | "ar-KW" | "ar-AE" | "ar-BH" | "ar-QA" | "ar-OM" | "pt-BR" | "pt-PT" | "ru-RU" | "ja-JP" | "de-DE" | "de-AT" | "de-CH" | "fr-FR" | "fr-CA" | "fr-BE" | "fr-CH" | "fr-LU" | "fr-MC" | "ko-KR" | "it-IT" | "it-CH" | "tr-TR" | "th-TH" | "el-GR" | "cs-CZ" | "sv-SE" | "sv-FI" | "hu-HU" | "fi-FI" | "da-DK" | "nb-NO" | "nn-NO" | "he-IL" | "id-ID" | "ms-MY" | "ms-BN" | "ro-RO" | "bg-BG" | "uk-UA" | "sk-SK" | "sl-SI" | "hr-HR" | "ca-ES" | "lt-LT" | "lv-LV" | "et-EE" | "sq-AL" | "mk-MK" | "be-BY" | "is-IS" | "gl-ES" | "eu-ES" | "af-ZA" | "sw-KE" | "ta-IN" | "te-IN" | "kn-IN" | "mr-IN" | "gu-IN" | "pa-IN" | "kok-IN" | "sa-IN" | "ur-PK" | "fa-IR" | "syr-SY" | "div-MV" | "ka-GE";
 //#endregion
-//#region src/index.d.ts
+//#region src/kotori.d.ts
 type Tags = BCP47LanguageTagName;
 type SubTags = BCP47LanguageTagName extends `${infer SubTag}-${string}` ? SubTag : never;
-type AllTags = Tags | SubTags;
+type BCP47LanguageTagNameWithSubTag = Tags | SubTags;
 type Trim<T extends string> = T extends ` ${infer R}` ? Trim<R> : T extends `${infer L} ` ? Trim<L> : T;
 type ExtractVariables<T extends string> = T extends `${string}{{${infer P}}}${infer Q}` ? Trim<P> | ExtractVariables<Q> : never;
 declare const _args: unique symbol;
-declare const kotori: <const Primary extends AllTags, const Secondary extends Exclude<AllTags, Primary>>(props: {
+/**
+ * Creates a scoped i18n instance for your app.
+ * Call once and export the returned utilities.
+ *
+ * @param config - Configuration options.
+ * @param config.primary - `BCP47LanguageTag` — The source language. Variable inference and
+ * secondary string validation are both driven by this language's strings.
+ * @param config.secondaries - `Exclude<BCP47LanguageTag, primary>[]` — Additional supported languages.
+ * Cannot include the primary language.
+ * @returns `{ d, r, useT, setLanguage, config }`
+ *
+ * @example
+ * ```ts
+ * // locales.ts
+ * import { kotori } from 'kotori'
+ *
+ * export const { d, r, useT, setLanguage } = kotori({
+ *   primary: 'en',
+ *   secondaries: ['zh', 'ja', 'ms'],
+ * })
+ * ```
+ */
+declare const kotori: <const Primary extends BCP47LanguageTagNameWithSubTag, const Secondary extends Exclude<BCP47LanguageTagNameWithSubTag, Primary>>(config: {
   primary: Primary;
   secondaries: Secondary[];
 }) => {
+  config: {
+    primary: Primary;
+    secondaries: Secondary[];
+  };
   setLanguage: (language: Primary | Secondary) => void;
+  /**
+   * Translates a dict to the current language and interpolates variables.
+   * For use **outside** React components — route guards, axios interceptors,
+   * utility functions, etc.
+   *
+   * ⚠️ Do not use inside React components. The React Compiler will memoize
+   * the result permanently since `r` is a stable module-level reference,
+   * causing stale translations after a language change. Use `t` from `useT()`
+   * inside components instead.
+   *
+   * @param dictionary - A dict created by `d()`.
+   * @param args - `Record<string, string | number>` — Variable values to interpolate.
+   * Required if the dict has variables, omitted if it doesn't.
+   * @returns `string` — The translated and interpolated string in the current language.
+   *
+   * @example
+   * ```ts
+   * import { r, greeting, intro } from './locales'
+   *
+   * r(greeting)                          // ✅ no args needed
+   * r(intro, { name: 'John', age: 30 })  // ✅ typed args
+   * r(intro)                             // ❌ compile error: missing args
+   * r(intro, { name: 'John', x: 1 })     // ❌ compile error: unknown key 'x'
+   *
+   * // route guard
+   * router.beforeEach(() => {
+   *   document.title = r(pageTitle)
+   * })
+   *
+   * // axios interceptor
+   * axios.interceptors.response.use(null, () => {
+   *   toast.error(r(errorMessage))
+   * })
+   * ```
+   */
   r: <Dictionary extends () => Readonly<{
     d: Record<Primary | Secondary, string>;
     [_args]?: Record<string, string | number>;
   }>>(dictionary: Dictionary, ...args: keyof NonNullable<ReturnType<Dictionary>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<Dictionary>[typeof _args]>]) => string;
+  /**
+   * Defines a translation unit. The primary language string drives variable
+   * inference — all secondary strings are validated against it at compile time.
+   *
+   * Call with an optional generic to narrow variable types beyond the default
+   * `string | number`. Supports TypeScript template literal types.
+   *
+   * @param dictionary - `Record<Language, string>` — One string per language.
+   * Variables are declared with `{{variableName}}` syntax. Spaces inside braces
+   * are trimmed — `{{ name }}` and `{{name}}` are equivalent.
+   * Secondary strings must use exactly the same variable names as the primary.
+   * @returns A function optionally accepting a generic to narrow variable types,
+   * which returns the translation unit.
+   *
+   * @example
+   * ```ts
+   * // no variables
+   * const greeting = d({ en: 'Hello', zh: '你好', ja: 'こんにちは', ms: 'Helo' })()
+   *
+   * // variables — inferred as Record<'name' | 'age', string | number> by default
+   * const intro = d({
+   *   en: 'My name is {{name}}, I am {{age}} years old.',
+   *   zh: '我叫{{name}}，我今年{{age}}岁了。',
+   *   ja: '私の名前は{{name}}で、{{age}}歳です。',
+   *   ms: 'Nama saya {{name}}, saya berumur {{age}} tahun.',
+   * })()
+   *
+   * // narrowed variable types via generic
+   * const clock = d({
+   *   en: 'Current time: {{hour}}:{{minute}}',
+   *   zh: '现在时间：{{hour}}:{{minute}}',
+   *   ja: '現在時刻：{{hour}}:{{minute}}',
+   *   ms: 'Masa semasa: {{hour}}:{{minute}}',
+   * })<{ hour: number; minute: number }>()
+   *
+   * // TypeScript template literal types work too
+   * const lastLogin = d({
+   *   en: 'Last login: {{date}}',
+   *   zh: '上次登录：{{date}}',
+   *   ja: '最終ログイン：{{date}}',
+   *   ms: 'Log masuk terakhir: {{date}}',
+   * })<{ date: `${number}-${number}-${number}` }>()
+   *
+   * // ❌ compile error — 'ja' translation missing
+   * const bad1 = d({ en: 'Hello', zh: '你好', ms: 'Helo' })()
+   *
+   * // ❌ compile error — secondary string has wrong variable name
+   * const bad2 = d({ en: 'Hello {{name}}', zh: '你好 {{naam}}', ja: 'こんにちは {{name}}', ms: 'Helo {{name}}' })()
+   *
+   * // ❌ compile error — secondary string missing a variable
+   * const bad3 = d({ en: '{{x}} {{y}}', zh: '{{x}}', ja: '{{x}} {{y}}', ms: '{{x}} {{y}}' })()
+   * ```
+   */
   d: <const PrimaryString extends string, const SecondaryObject extends { [Key in Secondary]: ExtractVariables<PrimaryString> extends infer PrimaryVariables ? ExtractVariables<SecondaryObject[Key] & string> extends infer SecondaryVariables ? PrimaryVariables[] extends SecondaryVariables[] ? SecondaryVariables[] extends PrimaryVariables[] ? SecondaryObject[Key] : "variables not match!" : "variables not match!!" : never : never }>(dictionary: { [Key in Primary]: PrimaryString } & SecondaryObject) => <const ArgsType extends Record<ExtractVariables<PrimaryString>, string | number> = Record<ExtractVariables<PrimaryString>, string | number>>() => Readonly<{
     d: typeof dictionary;
     [_args]?: ArgsType;
   }>;
+  /**
+   * React hook. Subscribes the component to language changes.
+   * Returns a snapshot containing the current `language` and a
+   * React Compiler-safe `t` function.
+   *
+   * Call in every component that renders translated strings.
+   * When `setLanguage` is called anywhere, all `useT()` consumers rerender.
+   *
+   * @returns `{ language: Language, t: TranslateFunction }`
+   * @returns `language` - `Language` — The current active language tag as a reactive value.
+   * @returns `t` - `TranslateFunction` — React Compiler-safe translate function. Use this inside components instead of the instance-level `t`.
+   *
+   * @example
+   * ```tsx
+   * import { useT, intro, time } from './locales'
+   *
+   * const Page = () => {
+   *   const { t, language } = useT()
+   *
+   *   return (
+   *     <>
+   *       <p>{t(intro, { name: 'John', age: 30 })}</p>
+   *       <p>{t(time, { hour: 12, minute: 0 })}</p>
+   *       <p>Current language: {language}</p>
+   *     </>
+   *   )
+   * }
+   * ```
+   */
   useT: () => {
     language: Primary | Secondary;
     t: <Dictionary extends () => Readonly<{
@@ -30,4 +173,75 @@ declare const kotori: <const Primary extends AllTags, const Secondary extends Ex
   };
 };
 //#endregion
-export { AllTags, SubTags, Tags, kotori };
+//#region src/detectLanguage.d.ts
+/**
+ * Detects the user's preferred language from browser settings and sets it
+ * on the kotori instance. Iterates through the user's full language preference
+ * list in order, stopping at the first match.
+ *
+ * @param instance - An object with `setLanguage` and `config`. Compatible with
+ * the kotori instance returned by `kotori()`, or any custom object that satisfies
+ * the same shape — allowing use with non-kotori setups.
+ * @param instance.setLanguage - `(language: BCP47LanguageTagNameWithSubTag) => void` — Called with the
+ * first matched language. Can be any callback — a kotori `setLanguage`, a React
+ * state setter, a Zustand action, etc.
+ * @param instance.config - Language configuration.
+ * @param instance.config.primary - `BCP47LanguageTagNameWithSubTag` — The primary/fallback language tag.
+ * @param instance.config.secondaries - `Exclude<AllTags, primary>[]` — Additional supported language tags. Cannot include the primary language.
+ * @param options - Detection options.
+ * @param options.fallbackToSubtag - `boolean` — If no exact match is found (e.g. `'zh-CN'`),
+ * fall back to the subtag (e.g. `'zh'`). Defaults to `true`.
+ * @returns `void` — Calls `setLanguage` on the first match. No-op if no match is found.
+ *
+ * @example
+ * ```ts
+ * // with kotori instance
+ * import { kotori, detectLanguage } from 'kotori'
+ *
+ * const i18n = kotori({
+ *   primary: 'en',
+ *   secondaries: ['zh', 'ja', 'ms'],
+ * })
+ *
+ * detectLanguage(i18n)
+ * // browser: ['zh-CN', 'en-US'] → subtag 'zh' → setLanguage('zh') ✅
+ *
+ * detectLanguage(i18n, { fallbackToSubtag: false })
+ * // browser: ['zh-CN'] → no exact match → no-op, stays 'en'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // ✅ setLanguage type exactly matches primary + secondaries union
+ * detectLanguage({
+ *   setLanguage: (lang: 'en' | 'zh' | 'ja') => setLang(lang),
+ *   config: {
+ *     primary: 'en',
+ *     secondaries: ['zh', 'ja'],
+ *   },
+ * })
+ *
+ * // ❌ compile error — setLanguage accepts wider type than declared
+ * detectLanguage({
+ *   setLanguage: (lang: string) => setLang(lang),
+ *   config: { primary: 'en', secondaries: ['zh'] },
+ * })
+ * ```
+ */
+declare const detectLanguage: <const T extends {
+  setLanguage: (language: Parameters<T["setLanguage"]>[0]) => void;
+  config: {
+    primary: BCP47LanguageTagNameWithSubTag;
+    secondaries: BCP47LanguageTagNameWithSubTag[];
+  };
+}>(instance: T["config"]["primary"] | T["config"]["secondaries"][number] extends infer A ? {
+  setLanguage: Parameters<T["setLanguage"]>[0] extends infer L ? L[] extends A[] ? A[] extends L[] ? (language: L) => void : "language param does not match primary or secondaries language types" : A : never;
+  config: {
+    primary: T["config"]["primary"];
+    secondaries: Exclude<BCP47LanguageTagNameWithSubTag, T["config"]["primary"]>[];
+  };
+} : T, options?: {
+  fallbackToSubtag?: boolean;
+}) => void;
+//#endregion
+export { BCP47LanguageTagNameWithSubTag, SubTags, Tags, detectLanguage, kotori };

package/dist/index.d.mts

@@ -1,26 +1,169 @@
 //#region node_modules/bcp47-language-tags/dist/zh.d.ts
 type BCP47LanguageTagName = "zh-CN" | "zh-TW" | "zh-HK" | "zh-MO" | "zh-SG" | "zh-CHS" | "zh-CHT" | "en-US" | "en-GB" | "en-CA" | "en-AU" | "en-IN" | "en-ZA" | "en-NZ" | "en-IE" | "en-PH" | "en-ZW" | "en-BZ" | "en-CB" | "en-JM" | "en-TT" | "hi-IN" | "es-ES" | "es-MX" | "es-AR" | "es-CO" | "es-PE" | "es-VE" | "es-CL" | "es-EC" | "es-GT" | "es-CU" | "es-BO" | "es-DO" | "es-HN" | "es-PY" | "es-SV" | "es-NI" | "es-PR" | "es-UY" | "es-PA" | "es-CR" | "ar-EG" | "ar-SA" | "ar-DZ" | "ar-MA" | "ar-IQ" | "ar-SD" | "ar-YE" | "ar-SY" | "ar-TN" | "ar-LY" | "ar-JO" | "ar-LB" | "ar-KW" | "ar-AE" | "ar-BH" | "ar-QA" | "ar-OM" | "pt-BR" | "pt-PT" | "ru-RU" | "ja-JP" | "de-DE" | "de-AT" | "de-CH" | "fr-FR" | "fr-CA" | "fr-BE" | "fr-CH" | "fr-LU" | "fr-MC" | "ko-KR" | "it-IT" | "it-CH" | "tr-TR" | "th-TH" | "el-GR" | "cs-CZ" | "sv-SE" | "sv-FI" | "hu-HU" | "fi-FI" | "da-DK" | "nb-NO" | "nn-NO" | "he-IL" | "id-ID" | "ms-MY" | "ms-BN" | "ro-RO" | "bg-BG" | "uk-UA" | "sk-SK" | "sl-SI" | "hr-HR" | "ca-ES" | "lt-LT" | "lv-LV" | "et-EE" | "sq-AL" | "mk-MK" | "be-BY" | "is-IS" | "gl-ES" | "eu-ES" | "af-ZA" | "sw-KE" | "ta-IN" | "te-IN" | "kn-IN" | "mr-IN" | "gu-IN" | "pa-IN" | "kok-IN" | "sa-IN" | "ur-PK" | "fa-IR" | "syr-SY" | "div-MV" | "ka-GE";
 //#endregion
-//#region src/index.d.ts
+//#region src/kotori.d.ts
 type Tags = BCP47LanguageTagName;
 type SubTags = BCP47LanguageTagName extends `${infer SubTag}-${string}` ? SubTag : never;
-type AllTags = Tags | SubTags;
+type BCP47LanguageTagNameWithSubTag = Tags | SubTags;
 type Trim<T extends string> = T extends ` ${infer R}` ? Trim<R> : T extends `${infer L} ` ? Trim<L> : T;
 type ExtractVariables<T extends string> = T extends `${string}{{${infer P}}}${infer Q}` ? Trim<P> | ExtractVariables<Q> : never;
 declare const _args: unique symbol;
-declare const kotori: <const Primary extends AllTags, const Secondary extends Exclude<AllTags, Primary>>(props: {
+/**
+ * Creates a scoped i18n instance for your app.
+ * Call once and export the returned utilities.
+ *
+ * @param config - Configuration options.
+ * @param config.primary - `BCP47LanguageTag` — The source language. Variable inference and
+ * secondary string validation are both driven by this language's strings.
+ * @param config.secondaries - `Exclude<BCP47LanguageTag, primary>[]` — Additional supported languages.
+ * Cannot include the primary language.
+ * @returns `{ d, r, useT, setLanguage, config }`
+ *
+ * @example
+ * ```ts
+ * // locales.ts
+ * import { kotori } from 'kotori'
+ *
+ * export const { d, r, useT, setLanguage } = kotori({
+ *   primary: 'en',
+ *   secondaries: ['zh', 'ja', 'ms'],
+ * })
+ * ```
+ */
+declare const kotori: <const Primary extends BCP47LanguageTagNameWithSubTag, const Secondary extends Exclude<BCP47LanguageTagNameWithSubTag, Primary>>(config: {
   primary: Primary;
   secondaries: Secondary[];
 }) => {
+  config: {
+    primary: Primary;
+    secondaries: Secondary[];
+  };
   setLanguage: (language: Primary | Secondary) => void;
+  /**
+   * Translates a dict to the current language and interpolates variables.
+   * For use **outside** React components — route guards, axios interceptors,
+   * utility functions, etc.
+   *
+   * ⚠️ Do not use inside React components. The React Compiler will memoize
+   * the result permanently since `r` is a stable module-level reference,
+   * causing stale translations after a language change. Use `t` from `useT()`
+   * inside components instead.
+   *
+   * @param dictionary - A dict created by `d()`.
+   * @param args - `Record<string, string | number>` — Variable values to interpolate.
+   * Required if the dict has variables, omitted if it doesn't.
+   * @returns `string` — The translated and interpolated string in the current language.
+   *
+   * @example
+   * ```ts
+   * import { r, greeting, intro } from './locales'
+   *
+   * r(greeting)                          // ✅ no args needed
+   * r(intro, { name: 'John', age: 30 })  // ✅ typed args
+   * r(intro)                             // ❌ compile error: missing args
+   * r(intro, { name: 'John', x: 1 })     // ❌ compile error: unknown key 'x'
+   *
+   * // route guard
+   * router.beforeEach(() => {
+   *   document.title = r(pageTitle)
+   * })
+   *
+   * // axios interceptor
+   * axios.interceptors.response.use(null, () => {
+   *   toast.error(r(errorMessage))
+   * })
+   * ```
+   */
   r: <Dictionary extends () => Readonly<{
     d: Record<Primary | Secondary, string>;
     [_args]?: Record<string, string | number>;
   }>>(dictionary: Dictionary, ...args: keyof NonNullable<ReturnType<Dictionary>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<Dictionary>[typeof _args]>]) => string;
+  /**
+   * Defines a translation unit. The primary language string drives variable
+   * inference — all secondary strings are validated against it at compile time.
+   *
+   * Call with an optional generic to narrow variable types beyond the default
+   * `string | number`. Supports TypeScript template literal types.
+   *
+   * @param dictionary - `Record<Language, string>` — One string per language.
+   * Variables are declared with `{{variableName}}` syntax. Spaces inside braces
+   * are trimmed — `{{ name }}` and `{{name}}` are equivalent.
+   * Secondary strings must use exactly the same variable names as the primary.
+   * @returns A function optionally accepting a generic to narrow variable types,
+   * which returns the translation unit.
+   *
+   * @example
+   * ```ts
+   * // no variables
+   * const greeting = d({ en: 'Hello', zh: '你好', ja: 'こんにちは', ms: 'Helo' })()
+   *
+   * // variables — inferred as Record<'name' | 'age', string | number> by default
+   * const intro = d({
+   *   en: 'My name is {{name}}, I am {{age}} years old.',
+   *   zh: '我叫{{name}}，我今年{{age}}岁了。',
+   *   ja: '私の名前は{{name}}で、{{age}}歳です。',
+   *   ms: 'Nama saya {{name}}, saya berumur {{age}} tahun.',
+   * })()
+   *
+   * // narrowed variable types via generic
+   * const clock = d({
+   *   en: 'Current time: {{hour}}:{{minute}}',
+   *   zh: '现在时间：{{hour}}:{{minute}}',
+   *   ja: '現在時刻：{{hour}}:{{minute}}',
+   *   ms: 'Masa semasa: {{hour}}:{{minute}}',
+   * })<{ hour: number; minute: number }>()
+   *
+   * // TypeScript template literal types work too
+   * const lastLogin = d({
+   *   en: 'Last login: {{date}}',
+   *   zh: '上次登录：{{date}}',
+   *   ja: '最終ログイン：{{date}}',
+   *   ms: 'Log masuk terakhir: {{date}}',
+   * })<{ date: `${number}-${number}-${number}` }>()
+   *
+   * // ❌ compile error — 'ja' translation missing
+   * const bad1 = d({ en: 'Hello', zh: '你好', ms: 'Helo' })()
+   *
+   * // ❌ compile error — secondary string has wrong variable name
+   * const bad2 = d({ en: 'Hello {{name}}', zh: '你好 {{naam}}', ja: 'こんにちは {{name}}', ms: 'Helo {{name}}' })()
+   *
+   * // ❌ compile error — secondary string missing a variable
+   * const bad3 = d({ en: '{{x}} {{y}}', zh: '{{x}}', ja: '{{x}} {{y}}', ms: '{{x}} {{y}}' })()
+   * ```
+   */
   d: <const PrimaryString extends string, const SecondaryObject extends { [Key in Secondary]: ExtractVariables<PrimaryString> extends infer PrimaryVariables ? ExtractVariables<SecondaryObject[Key] & string> extends infer SecondaryVariables ? PrimaryVariables[] extends SecondaryVariables[] ? SecondaryVariables[] extends PrimaryVariables[] ? SecondaryObject[Key] : "variables not match!" : "variables not match!!" : never : never }>(dictionary: { [Key in Primary]: PrimaryString } & SecondaryObject) => <const ArgsType extends Record<ExtractVariables<PrimaryString>, string | number> = Record<ExtractVariables<PrimaryString>, string | number>>() => Readonly<{
     d: typeof dictionary;
     [_args]?: ArgsType;
   }>;
+  /**
+   * React hook. Subscribes the component to language changes.
+   * Returns a snapshot containing the current `language` and a
+   * React Compiler-safe `t` function.
+   *
+   * Call in every component that renders translated strings.
+   * When `setLanguage` is called anywhere, all `useT()` consumers rerender.
+   *
+   * @returns `{ language: Language, t: TranslateFunction }`
+   * @returns `language` - `Language` — The current active language tag as a reactive value.
+   * @returns `t` - `TranslateFunction` — React Compiler-safe translate function. Use this inside components instead of the instance-level `t`.
+   *
+   * @example
+   * ```tsx
+   * import { useT, intro, time } from './locales'
+   *
+   * const Page = () => {
+   *   const { t, language } = useT()
+   *
+   *   return (
+   *     <>
+   *       <p>{t(intro, { name: 'John', age: 30 })}</p>
+   *       <p>{t(time, { hour: 12, minute: 0 })}</p>
+   *       <p>Current language: {language}</p>
+   *     </>
+   *   )
+   * }
+   * ```
+   */
   useT: () => {
     language: Primary | Secondary;
     t: <Dictionary extends () => Readonly<{
@@ -30,4 +173,75 @@ declare const kotori: <const Primary extends AllTags, const Secondary extends Ex
   };
 };
 //#endregion
-export { AllTags, SubTags, Tags, kotori };
+//#region src/detectLanguage.d.ts
+/**
+ * Detects the user's preferred language from browser settings and sets it
+ * on the kotori instance. Iterates through the user's full language preference
+ * list in order, stopping at the first match.
+ *
+ * @param instance - An object with `setLanguage` and `config`. Compatible with
+ * the kotori instance returned by `kotori()`, or any custom object that satisfies
+ * the same shape — allowing use with non-kotori setups.
+ * @param instance.setLanguage - `(language: BCP47LanguageTagNameWithSubTag) => void` — Called with the
+ * first matched language. Can be any callback — a kotori `setLanguage`, a React
+ * state setter, a Zustand action, etc.
+ * @param instance.config - Language configuration.
+ * @param instance.config.primary - `BCP47LanguageTagNameWithSubTag` — The primary/fallback language tag.
+ * @param instance.config.secondaries - `Exclude<AllTags, primary>[]` — Additional supported language tags. Cannot include the primary language.
+ * @param options - Detection options.
+ * @param options.fallbackToSubtag - `boolean` — If no exact match is found (e.g. `'zh-CN'`),
+ * fall back to the subtag (e.g. `'zh'`). Defaults to `true`.
+ * @returns `void` — Calls `setLanguage` on the first match. No-op if no match is found.
+ *
+ * @example
+ * ```ts
+ * // with kotori instance
+ * import { kotori, detectLanguage } from 'kotori'
+ *
+ * const i18n = kotori({
+ *   primary: 'en',
+ *   secondaries: ['zh', 'ja', 'ms'],
+ * })
+ *
+ * detectLanguage(i18n)
+ * // browser: ['zh-CN', 'en-US'] → subtag 'zh' → setLanguage('zh') ✅
+ *
+ * detectLanguage(i18n, { fallbackToSubtag: false })
+ * // browser: ['zh-CN'] → no exact match → no-op, stays 'en'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // ✅ setLanguage type exactly matches primary + secondaries union
+ * detectLanguage({
+ *   setLanguage: (lang: 'en' | 'zh' | 'ja') => setLang(lang),
+ *   config: {
+ *     primary: 'en',
+ *     secondaries: ['zh', 'ja'],
+ *   },
+ * })
+ *
+ * // ❌ compile error — setLanguage accepts wider type than declared
+ * detectLanguage({
+ *   setLanguage: (lang: string) => setLang(lang),
+ *   config: { primary: 'en', secondaries: ['zh'] },
+ * })
+ * ```
+ */
+declare const detectLanguage: <const T extends {
+  setLanguage: (language: Parameters<T["setLanguage"]>[0]) => void;
+  config: {
+    primary: BCP47LanguageTagNameWithSubTag;
+    secondaries: BCP47LanguageTagNameWithSubTag[];
+  };
+}>(instance: T["config"]["primary"] | T["config"]["secondaries"][number] extends infer A ? {
+  setLanguage: Parameters<T["setLanguage"]>[0] extends infer L ? L[] extends A[] ? A[] extends L[] ? (language: L) => void : "language param does not match primary or secondaries language types" : A : never;
+  config: {
+    primary: T["config"]["primary"];
+    secondaries: Exclude<BCP47LanguageTagNameWithSubTag, T["config"]["primary"]>[];
+  };
+} : T, options?: {
+  fallbackToSubtag?: boolean;
+}) => void;
+//#endregion
+export { BCP47LanguageTagNameWithSubTag, SubTags, Tags, detectLanguage, kotori };

package/dist/index.mjs

@@ -1,12 +1,144 @@
 import { useSyncExternalStore } from "react";
-//#region src/index.ts
-const kotori = (props) => {
+//#region src/detectLanguage.ts
+/**
+* Detects the user's preferred language from browser settings and sets it
+* on the kotori instance. Iterates through the user's full language preference
+* list in order, stopping at the first match.
+*
+* @param instance - An object with `setLanguage` and `config`. Compatible with
+* the kotori instance returned by `kotori()`, or any custom object that satisfies
+* the same shape — allowing use with non-kotori setups.
+* @param instance.setLanguage - `(language: BCP47LanguageTagNameWithSubTag) => void` — Called with the
+* first matched language. Can be any callback — a kotori `setLanguage`, a React
+* state setter, a Zustand action, etc.
+* @param instance.config - Language configuration.
+* @param instance.config.primary - `BCP47LanguageTagNameWithSubTag` — The primary/fallback language tag.
+* @param instance.config.secondaries - `Exclude<AllTags, primary>[]` — Additional supported language tags. Cannot include the primary language.
+* @param options - Detection options.
+* @param options.fallbackToSubtag - `boolean` — If no exact match is found (e.g. `'zh-CN'`),
+* fall back to the subtag (e.g. `'zh'`). Defaults to `true`.
+* @returns `void` — Calls `setLanguage` on the first match. No-op if no match is found.
+*
+* @example
+* ```ts
+* // with kotori instance
+* import { kotori, detectLanguage } from 'kotori'
+*
+* const i18n = kotori({
+*   primary: 'en',
+*   secondaries: ['zh', 'ja', 'ms'],
+* })
+*
+* detectLanguage(i18n)
+* // browser: ['zh-CN', 'en-US'] → subtag 'zh' → setLanguage('zh') ✅
+*
+* detectLanguage(i18n, { fallbackToSubtag: false })
+* // browser: ['zh-CN'] → no exact match → no-op, stays 'en'
+* ```
+*
+* @example
+* ```ts
+* // ✅ setLanguage type exactly matches primary + secondaries union
+* detectLanguage({
+*   setLanguage: (lang: 'en' | 'zh' | 'ja') => setLang(lang),
+*   config: {
+*     primary: 'en',
+*     secondaries: ['zh', 'ja'],
+*   },
+* })
+*
+* // ❌ compile error — setLanguage accepts wider type than declared
+* detectLanguage({
+*   setLanguage: (lang: string) => setLang(lang),
+*   config: { primary: 'en', secondaries: ['zh'] },
+* })
+* ```
+*/
+const detectLanguage = (instance, options = { fallbackToSubtag: true }) => {
+	const languages = [instance.config.primary, ...instance.config.secondaries];
+	for (const browserLang of navigator.languages) {
+		if (languages.includes(browserLang)) return instance.setLanguage(browserLang);
+		if (options.fallbackToSubtag) {
+			const subtag = browserLang.split("-")[0];
+			if (languages.includes(subtag)) return instance.setLanguage(subtag);
+		}
+	}
+};
+//#endregion
+//#region src/kotori.ts
+/**
+* Creates a scoped i18n instance for your app.
+* Call once and export the returned utilities.
+*
+* @param config - Configuration options.
+* @param config.primary - `BCP47LanguageTag` — The source language. Variable inference and
+* secondary string validation are both driven by this language's strings.
+* @param config.secondaries - `Exclude<BCP47LanguageTag, primary>[]` — Additional supported languages.
+* Cannot include the primary language.
+* @returns `{ d, r, useT, setLanguage, config }`
+*
+* @example
+* ```ts
+* // locales.ts
+* import { kotori } from 'kotori'
+*
+* export const { d, r, useT, setLanguage } = kotori({
+*   primary: 'en',
+*   secondaries: ['zh', 'ja', 'ms'],
+* })
+* ```
+*/
+const kotori = (config) => {
 	const listeners = /* @__PURE__ */ new Set();
+	/**
+	* Translates a dict to the current language and interpolates variables.
+	*
+	* @param dictionary - A dict created by `d()`.
+	* @param args - `Record<string, string | number>` — Variable values to interpolate. Required if the dict has variables, omitted if it doesn't.
+	* @returns `string` — The translated and interpolated string.
+	*
+	* @example
+	* const Intro = () => {
+	*     const { t } = useT()
+	*
+	*     return (
+	*         <p>{t(greeting)}</p>                             // ✅ no args needed
+	*         <p>{t(intro, { name: 'John', age: 30 })}</p>     // ✅ typed args
+	*         <p>{t(intro)}</p>                                // ❌ compile error: missing args
+	*         <p>{t(intro, { name: 'John', x: 30 })}</p>       // ❌ compile error: unknown key 'x'
+	*     )
+	* }
+	*/
 	const t = (dictionary, ...args) => (dictionary().d[snapshot.language] || "").replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, key) => String(args[0]?.[key]));
 	let snapshot = {
-		language: props.primary,
+		language: config.primary,
 		t
 	};
+	/**
+	* Updates the current language and triggers a rerender in all active
+	* `useT()` consumers across all pages. Safe to call outside React.
+	*
+	* @param language - `Language` — Must be one of the tags declared in
+	* `primary` or `secondaries`. Any other value is a compile error.
+	* @returns `void`
+	*
+	* @example
+	* ```ts
+	* import { setLanguage } from './locales'
+	*
+	* setLanguage('zh')      // ✅
+	* setLanguage('ms')      // ✅
+	* setLanguage('de')      // ❌ compile error: 'de' was not declared
+	*
+	* // persist and restore language selection
+	* setLanguage('zh')
+	* localStorage.setItem('lang', 'zh')
+	*
+	* // restore on app startup
+	* const saved = localStorage.getItem('lang')
+	* if (saved) setLanguage(saved as 'en')
+	* ```
+	*/
 	const setLanguage = (language) => {
 		snapshot = {
 			language,
@@ -23,11 +155,129 @@ const kotori = (props) => {
 		};
 	};
 	return {
+		config,
 		setLanguage,
+		/**
+		* Translates a dict to the current language and interpolates variables.
+		* For use **outside** React components — route guards, axios interceptors,
+		* utility functions, etc.
+		*
+		* ⚠️ Do not use inside React components. The React Compiler will memoize
+		* the result permanently since `r` is a stable module-level reference,
+		* causing stale translations after a language change. Use `t` from `useT()`
+		* inside components instead.
+		*
+		* @param dictionary - A dict created by `d()`.
+		* @param args - `Record<string, string | number>` — Variable values to interpolate.
+		* Required if the dict has variables, omitted if it doesn't.
+		* @returns `string` — The translated and interpolated string in the current language.
+		*
+		* @example
+		* ```ts
+		* import { r, greeting, intro } from './locales'
+		*
+		* r(greeting)                          // ✅ no args needed
+		* r(intro, { name: 'John', age: 30 })  // ✅ typed args
+		* r(intro)                             // ❌ compile error: missing args
+		* r(intro, { name: 'John', x: 1 })     // ❌ compile error: unknown key 'x'
+		*
+		* // route guard
+		* router.beforeEach(() => {
+		*   document.title = r(pageTitle)
+		* })
+		*
+		* // axios interceptor
+		* axios.interceptors.response.use(null, () => {
+		*   toast.error(r(errorMessage))
+		* })
+		* ```
+		*/
 		r: t,
+		/**
+		* Defines a translation unit. The primary language string drives variable
+		* inference — all secondary strings are validated against it at compile time.
+		*
+		* Call with an optional generic to narrow variable types beyond the default
+		* `string | number`. Supports TypeScript template literal types.
+		*
+		* @param dictionary - `Record<Language, string>` — One string per language.
+		* Variables are declared with `{{variableName}}` syntax. Spaces inside braces
+		* are trimmed — `{{ name }}` and `{{name}}` are equivalent.
+		* Secondary strings must use exactly the same variable names as the primary.
+		* @returns A function optionally accepting a generic to narrow variable types,
+		* which returns the translation unit.
+		*
+		* @example
+		* ```ts
+		* // no variables
+		* const greeting = d({ en: 'Hello', zh: '你好', ja: 'こんにちは', ms: 'Helo' })()
+		*
+		* // variables — inferred as Record<'name' | 'age', string | number> by default
+		* const intro = d({
+		*   en: 'My name is {{name}}, I am {{age}} years old.',
+		*   zh: '我叫{{name}}，我今年{{age}}岁了。',
+		*   ja: '私の名前は{{name}}で、{{age}}歳です。',
+		*   ms: 'Nama saya {{name}}, saya berumur {{age}} tahun.',
+		* })()
+		*
+		* // narrowed variable types via generic
+		* const clock = d({
+		*   en: 'Current time: {{hour}}:{{minute}}',
+		*   zh: '现在时间：{{hour}}:{{minute}}',
+		*   ja: '現在時刻：{{hour}}:{{minute}}',
+		*   ms: 'Masa semasa: {{hour}}:{{minute}}',
+		* })<{ hour: number; minute: number }>()
+		*
+		* // TypeScript template literal types work too
+		* const lastLogin = d({
+		*   en: 'Last login: {{date}}',
+		*   zh: '上次登录：{{date}}',
+		*   ja: '最終ログイン：{{date}}',
+		*   ms: 'Log masuk terakhir: {{date}}',
+		* })<{ date: `${number}-${number}-${number}` }>()
+		*
+		* // ❌ compile error — 'ja' translation missing
+		* const bad1 = d({ en: 'Hello', zh: '你好', ms: 'Helo' })()
+		*
+		* // ❌ compile error — secondary string has wrong variable name
+		* const bad2 = d({ en: 'Hello {{name}}', zh: '你好 {{naam}}', ja: 'こんにちは {{name}}', ms: 'Helo {{name}}' })()
+		*
+		* // ❌ compile error — secondary string missing a variable
+		* const bad3 = d({ en: '{{x}} {{y}}', zh: '{{x}}', ja: '{{x}} {{y}}', ms: '{{x}} {{y}}' })()
+		* ```
+		*/
 		d: (dictionary) => () => ({ d: dictionary }),
+		/**
+		* React hook. Subscribes the component to language changes.
+		* Returns a snapshot containing the current `language` and a
+		* React Compiler-safe `t` function.
+		*
+		* Call in every component that renders translated strings.
+		* When `setLanguage` is called anywhere, all `useT()` consumers rerender.
+		*
+		* @returns `{ language: Language, t: TranslateFunction }`
+		* @returns `language` - `Language` — The current active language tag as a reactive value.
+		* @returns `t` - `TranslateFunction` — React Compiler-safe translate function. Use this inside components instead of the instance-level `t`.
+		*
+		* @example
+		* ```tsx
+		* import { useT, intro, time } from './locales'
+		*
+		* const Page = () => {
+		*   const { t, language } = useT()
+		*
+		*   return (
+		*     <>
+		*       <p>{t(intro, { name: 'John', age: 30 })}</p>
+		*       <p>{t(time, { hour: 12, minute: 0 })}</p>
+		*       <p>Current language: {language}</p>
+		*     </>
+		*   )
+		* }
+		* ```
+		*/
 		useT: () => useSyncExternalStore(subscribe, () => snapshot, () => snapshot)
 	};
 };
 //#endregion
-export { kotori };
+export { detectLanguage, kotori };

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "kotori",
 	"description": "0.28kB Strongly-typed and tree-shakeable internationalization library for React",
-	"version": "6.0.0",
+	"version": "6.1.0",
 	"scripts": {
 		"setup": "rm -rf node_modules && npm i && git init && husky",
 		"prepublishOnly": "npm i && npx tsc && npm run build",