kotori 5.0.11 → 6.0.0

package/README.md

@@ -15,13 +15,13 @@
 </p>
 
 ```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?', 
 
@@ -34,18 +34,21 @@ 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
@@ -73,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}}',
@@ -98,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 (
         <>
@@ -126,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}}',
@@ -145,7 +148,7 @@ const lastLogin = dict({
 
 export const Page2 = () => {
 
-    useT()
+    const { t } = useT()
 
     return (
         <>
@@ -167,31 +170,31 @@ 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` | `BCP47LanguageTag` | The source language. Drives variable inference. |
+| `secondaries` | `BCP47LanguageTag[]` | Additional supported languages. |
 
-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. Return `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
 }>
@@ -205,20 +208,32 @@ 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.
 
-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.
+⚠️ 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 language = useT()
+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
+<p>{t(intro, { name: 'John', age: 30 })}</p>
 ```
 
 ## Language Tags
@@ -227,8 +242,8 @@ kotori uses [BCP 47](https://www.iana.org/assignments/language-subtag-registry/l
 
 ## Tips
 
-- If you plan to add new languages frequently, consider colocating all your dicts in a single file. 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. 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.
+- 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.  
 - Both approaches are tree-shakeable — only the dicts imported by the current page are included in its bundle.
 
 ## Roadmap
@@ -238,10 +253,9 @@ kotori uses [BCP 47](https://www.iana.org/assignments/language-subtag-registry/l
 - 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.

package/dist/index.cjs

@@ -3,9 +3,16 @@ let react = require("react");
 //#region src/index.ts
 const kotori = (props) => {
 	const listeners = /* @__PURE__ */ new Set();
-	let language = props.primaryLanguageTag;
-	const setLanguage = (tag) => {
-		language = tag;
+	const t = (dictionary, ...args) => (dictionary().d[snapshot.language] || "").replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, key) => String(args[0]?.[key]));
+	let snapshot = {
+		language: props.primary,
+		t
+	};
+	const setLanguage = (language) => {
+		snapshot = {
+			language,
+			t: (...args) => t(...args)
+		};
 		listeners.forEach((listener) => {
 			listener();
 		});
@@ -16,12 +23,11 @@ const kotori = (props) => {
 			listeners.delete(listener);
 		};
 	};
-	const t = (dict, ...args) => (dict().translation[language] || "").replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, key) => String(args[0]?.[key]));
 	return {
 		setLanguage,
-		t,
-		dict: (translation) => () => ({ translation }),
-		useT: () => (0, react.useSyncExternalStore)(subscribe, () => language, () => language)
+		r: t,
+		d: (dictionary) => () => ({ d: dictionary }),
+		useT: () => (0, react.useSyncExternalStore)(subscribe, () => snapshot, () => snapshot)
 	};
 };
 //#endregion

package/dist/index.d.cts

@@ -8,20 +8,26 @@ type AllTags = 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 PrimaryTag extends AllTags, const SecondaryTags extends Exclude<AllTags, PrimaryTag>>(props: {
-  primaryLanguageTag: PrimaryTag;
-  secondaryLanguageTags: SecondaryTags[];
+declare const kotori: <const Primary extends AllTags, const Secondary extends Exclude<AllTags, Primary>>(props: {
+  primary: Primary;
+  secondaries: Secondary[];
 }) => {
-  setLanguage: (tag: PrimaryTag | SecondaryTags) => void;
-  t: <Dict extends () => Readonly<{
-    translation: Record<PrimaryTag | SecondaryTags, string>;
+  setLanguage: (language: Primary | Secondary) => void;
+  r: <Dictionary extends () => Readonly<{
+    d: Record<Primary | Secondary, string>;
     [_args]?: Record<string, string | number>;
-  }>>(dict: Dict, ...args: keyof NonNullable<ReturnType<Dict>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<Dict>[typeof _args]>]) => string;
-  dict: <const PrimaryString extends string, const SecondaryObject extends { [Key in SecondaryTags]: 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 }>(translation: { [Key in PrimaryTag]: PrimaryString } & SecondaryObject) => <const ArgsType extends Record<ExtractVariables<PrimaryString>, string | number> = Record<ExtractVariables<PrimaryString>, string | number>>() => Readonly<{
-    translation: typeof translation;
+  }>>(dictionary: Dictionary, ...args: keyof NonNullable<ReturnType<Dictionary>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<Dictionary>[typeof _args]>]) => string;
+  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;
   }>;
-  useT: () => PrimaryTag | SecondaryTags;
+  useT: () => {
+    language: Primary | Secondary;
+    t: <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;
+  };
 };
 //#endregion
 export { AllTags, SubTags, Tags, kotori };

package/dist/index.d.mts

@@ -8,20 +8,26 @@ type AllTags = 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 PrimaryTag extends AllTags, const SecondaryTags extends Exclude<AllTags, PrimaryTag>>(props: {
-  primaryLanguageTag: PrimaryTag;
-  secondaryLanguageTags: SecondaryTags[];
+declare const kotori: <const Primary extends AllTags, const Secondary extends Exclude<AllTags, Primary>>(props: {
+  primary: Primary;
+  secondaries: Secondary[];
 }) => {
-  setLanguage: (tag: PrimaryTag | SecondaryTags) => void;
-  t: <Dict extends () => Readonly<{
-    translation: Record<PrimaryTag | SecondaryTags, string>;
+  setLanguage: (language: Primary | Secondary) => void;
+  r: <Dictionary extends () => Readonly<{
+    d: Record<Primary | Secondary, string>;
     [_args]?: Record<string, string | number>;
-  }>>(dict: Dict, ...args: keyof NonNullable<ReturnType<Dict>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<Dict>[typeof _args]>]) => string;
-  dict: <const PrimaryString extends string, const SecondaryObject extends { [Key in SecondaryTags]: 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 }>(translation: { [Key in PrimaryTag]: PrimaryString } & SecondaryObject) => <const ArgsType extends Record<ExtractVariables<PrimaryString>, string | number> = Record<ExtractVariables<PrimaryString>, string | number>>() => Readonly<{
-    translation: typeof translation;
+  }>>(dictionary: Dictionary, ...args: keyof NonNullable<ReturnType<Dictionary>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<Dictionary>[typeof _args]>]) => string;
+  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;
   }>;
-  useT: () => PrimaryTag | SecondaryTags;
+  useT: () => {
+    language: Primary | Secondary;
+    t: <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;
+  };
 };
 //#endregion
 export { AllTags, SubTags, Tags, kotori };

package/dist/index.mjs

@@ -2,9 +2,16 @@ import { useSyncExternalStore } from "react";
 //#region src/index.ts
 const kotori = (props) => {
 	const listeners = /* @__PURE__ */ new Set();
-	let language = props.primaryLanguageTag;
-	const setLanguage = (tag) => {
-		language = tag;
+	const t = (dictionary, ...args) => (dictionary().d[snapshot.language] || "").replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, key) => String(args[0]?.[key]));
+	let snapshot = {
+		language: props.primary,
+		t
+	};
+	const setLanguage = (language) => {
+		snapshot = {
+			language,
+			t: (...args) => t(...args)
+		};
 		listeners.forEach((listener) => {
 			listener();
 		});
@@ -15,12 +22,11 @@ const kotori = (props) => {
 			listeners.delete(listener);
 		};
 	};
-	const t = (dict, ...args) => (dict().translation[language] || "").replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, key) => String(args[0]?.[key]));
 	return {
 		setLanguage,
-		t,
-		dict: (translation) => () => ({ translation }),
-		useT: () => useSyncExternalStore(subscribe, () => language, () => language)
+		r: t,
+		d: (dictionary) => () => ({ d: dictionary }),
+		useT: () => useSyncExternalStore(subscribe, () => snapshot, () => snapshot)
 	};
 };
 //#endregion

package/package.json

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