kotori 5.0.12 → 6.1.0

package/README.md

@@ -11,21 +11,17 @@
 </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>
 
-## Note
-
-⚠️ Doesn't work with React Compiler!!
-
 ```ts
-const { dict, t } = kotori({
-    primaryLanguageTag: 'en',
-    secondaryLanguageTags: ['zh', 'ja', 'ms'],
+const { d, useT } = kotori({
+    primary: 'en',
+    secondaries: ['zh', 'ja', 'ms'],
 })
 
 // ❌ TypeScript error: missing japanese translation
-const intro = dict({ 
+const intro = d({ 
     // ⭐ base string drives the type contract
     en: 'Hello {{name}}, is it {{time}} now?', 
 
@@ -38,31 +34,34 @@ const intro = dict({
 // optional: type your arguments, by default it's `Record<'name'|'time', string | number>` in this example
 })<{name: string; time: `${number}:${number}`}> 
 
+const Component = () => {
+    const { t } = useT()
 
-// ✅ Works
-t(intro, { name: 'John', time: '12:25' }) 
+    // ✅ Works
+    t(intro, { name: 'John', time: '12:25' }) 
 
-// ❌ TypeScript error: missing { name }
-t(intro, { time: '12:25' })
+    // ❌ TypeScript error: missing { name }
+    t(intro, { time: '12:25' })
 
-// ❌ TypeScript error: unknown key 'nama'                   
-t(intro, { nama: 'John', time: '12:25' }) 
+    // ❌ TypeScript error: unknown key 'nama'                   
+    t(intro, { nama: 'John', time: '12:25' }) 
 
-// ❌ TypeScript error: invalid format for 'time'
-t(intro, { name: 'John', time: '12-00' }) 
+    // ❌ TypeScript error: invalid format for 'time'
+    t(intro, { name: 'John', time: '12-00' }) 
+}
 ```
 
 - No codegen
 - 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
 
@@ -77,20 +76,20 @@ npm i kotori
 ```ts
 import { kotori } from 'kotori'
 
-export const { useT, dict, setLanguage, t } = kotori({
-    primaryLanguageTag: 'en',
-    secondaryLanguageTags: ['zh', 'ja', 'ms'],
+export const { useT, d, setLanguage } = kotori({
+    primary: 'en',
+    secondaries: ['zh', 'ja', 'ms'],
 })
 
 // you can define your dicts in the same file or separate them by component, it's up to you
-export const intro = dict({
+export 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.',
 })
 
-export const time = dict({
+export const time = d({
     en: 'time {{time}}',
     zh: '时间 {{time}}',
     ja: '時間 {{time}}',
@@ -102,11 +101,11 @@ export const time = dict({
 ### page1.tsx
 
 ```tsx
-import { useT, dict, setLanguage, t, intro, time } from './locales'
+import { useT, setLanguage, intro, time } from './locales'
 
 export const Page1 = () => {
 
-    const language  = useT()
+    const { language, t } = useT()
 
     return (
         <>
@@ -130,17 +129,17 @@ export const Page1 = () => {
 ### page2.tsx
 
 ```tsx
-import { useT, dict, setLanguage, t, } from './locales'
+import { useT, d } from './locales'
 
 // you can also define dicts in the same file as your components, it's up to you
-const weather = dict({
+const weather = d({
     en: 'The weather in {{city}} has {{humidity}}% humidity.',
     zh: '{{city}}的天气湿度为{{humidity}}%。',
     ja: '{{city}}の湿度は{{humidity}}%です。',
     ms: 'Cuaca di {{city}} mempunyai kelembapan {{humidity}}%.',
 })<{ city: string; humidity: number }>
 
-const lastLogin = dict({
+const lastLogin = d({
     en: 'Last login: {{date}} at {{time}}',
     zh: '上次登录：{{date}} {{time}}',
     ja: '最終ログイン：{{date}} {{time}}',
@@ -149,7 +148,7 @@ const lastLogin = dict({
 
 export const Page2 = () => {
 
-    useT()
+    const { t } = useT()
 
     return (
         <>
@@ -164,38 +163,38 @@ export const Page2 = () => {
 
 ![how kotori works](image.webp) 
 
-### `kotori(options)`
+### `kotori(options)` (0.29kB)
 
 Creates a scoped i18n instance.
 
 ```ts
 import { kotori } from 'kotori'
 
-export const { useT, dict, setLanguage } = kotori({
-    primaryLanguageTag: 'en',
-    secondaryLanguageTags: ['zh', 'ja', 'ms'],
+export const { useT, d, setLanguage } = kotori({
+    primary: 'en',
+    secondaries: ['zh', 'ja', 'ms'],
 })
 ```
 
 | option | type | description |
 | --- | --- | --- |
-| `primaryLanguageTag` | `BCP47LanguageTag` | The source language. Drives variable inference. |
-| `secondaryLanguageTags` | `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 `{ dict, useT, setLanguage, t }`.
+Returns `{ d, useT, setLanguage, r }`.
 
-### `dict(translations)<argsType?>`
+### `d(translations)<argsType?>`
 
-Defines a translation unit. Takes one string per language.
+Defines a translation unit. Takes one string per language. Returns a `dictionary` object.
 
 ```ts
-const time = dict({ en: '{{hour}}:{{minute}}' })
+const time = d({ en: '{{hour}}:{{minute}}' })
 ```
 
 By default, variables are typed as `string | number`. Pass a generic to narrow them:
 
 ```ts
-const time = dict({ en: '{{hour}}:{{minute}}' })<{
+const time = d({ en: '{{hour}}:{{minute}}' })<{
     hour: number
     minute: number
 }>
@@ -209,43 +208,101 @@ Updates the current language and rerenders all active `useT` consumers across al
 setLanguage('zh')
 ```
 
-### `t(dict, args?)` 
+### `r(dictionary, args?)`
 
-Returns the translated string for the current language. `args` is required if the string has variables, omitted if it doesn't. Available directly on the `kotori` instance for non-React usage.
+Returns the translated string for the current language. `args` is required if the string has variables, omitted if it doesn't.
+
+⚠️ 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
-<p>{t(intro, { name: 'John', age: 30 })}</p>
+r(intro, { name: 'John', age: 30 })
 ```
 
 ### `useT()`
 
-React hook. Returns the current language tag as a reactive value. Updates when `setLanguage` is called.
+React hook. Returns the current language tag as a reactive value. Updates when `setLanguage` is called. Returns `{ t, language }`.
+
+```ts
+const { t, language } = useT()
+```
+
+### `t(dictionary, args?)`
+
+Returns the translated string for the current language. `args` is required if the string has variables, omitted if it doesn't.
+
+React version of `r(dictionary, args?)`, works with React Compiler.
+
+```tsx
+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
-const language = useT()
+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
 - Value formatting (date, number, currency)
-- Support for non-React frameworks (Vue, Svelte, Angular, etc.)
 
 ## Trivial
 
-There are already a lot of 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.
+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,11 +1,150 @@
 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();
-	let language = props.primaryLanguageTag;
-	const setLanguage = (tag) => {
-		language = tag;
+	/**
+	* 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: 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,
+			t: (...args) => t(...args)
+		};
 		listeners.forEach((listener) => {
 			listener();
 		});
@@ -16,13 +155,131 @@ const kotori = (props) => {
 			listeners.delete(listener);
 		};
 	};
-	const t = (dict, ...args) => (dict().translation[language] || "").replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, key) => String(args[0]?.[key]));
 	return {
+		config,
 		setLanguage,
-		t,
-		dict: (translation) => () => ({ translation }),
-		useT: () => (0, react.useSyncExternalStore)(subscribe, () => language, () => language)
+		/**
+		* 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;