kotori 1.0.2 → 2.0.0

package/README.md

@@ -14,26 +14,19 @@ const { dict } = kotori({
 const intro = dict({ 
     // ⭐ base string drives the type contract
     en: 'Hello {{name}}, is it {{time}} now?', 
-
      // ❌ TypeScript error: missing key 'name' 
     zh: '你好，现在是 {{time}} 吗？',
-
     // ❌ TypeScript error: unknown key 'nam'      
     ms: 'Hai {{nam}}, adakah pukul {{time}} sekarang?'  
-
 // optional: type your arguments, by default it's `Record<'name'|'time', string | number>` in this example
 })<{name: string; time: `${number}:${number}`}> 
 
-
 // ✅ Works
 t('intro', { name: 'John', 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: invalid format for 'time'
 t('intro', { name: 'John', time: '12-00' }) 
 ```
@@ -42,11 +35,11 @@ t('intro', { name: 'John', time: '12-00' })
 - No JSON
 - No dependencies
 - No build step
-- 0.34kb gzipped
+- 0.38kb 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
+- Translation keys are typed — no more string typos
+- Variables typed and inferred from string literals
 
 Demo: <https://stackblitz.com/edit/vitejs-vite-nyxwmhre?file=src%2FApp.tsx>
 
@@ -63,7 +56,7 @@ npm i kotori
 ```ts
 import { kotori } from './kotori'
 
-export const { useT, dict, setLanguage } = kotori({
+export const { createT, dict, setLanguage } = kotori({
     primaryLanguageTag: 'en',
     secondaryLanguageTags: ['zh', 'ja', 'ms'],
 })
@@ -72,7 +65,7 @@ export const { useT, dict, setLanguage } = kotori({
 **page1.tsx**
 
 ```tsx
-import { useT, dict } from './utils'
+import { createT, dict } from './utils'
 
 const intro = dict({
     en: 'my name is {{name}}, I am {{age}} years old.',
@@ -89,6 +82,11 @@ const time = dict({
 // optional: type your arguments, by default it's `Record<'time', string | number>` in this example
 })<{ time: `${number}:${number}:${number}` }> 
 
+const { useT } = createT({
+    intro,
+    time,
+})
+
 export const Page1 = () => {
     const { t, language, setLanguage } = useT()
     return (
@@ -113,7 +111,7 @@ export const Page1 = () => {
 **page2.tsx**
 
 ```tsx
-import { useT, dict } from './utils'
+import { createT, dict } from './utils'
 
 const weather = dict({
     en: 'The weather in {{city}} has {{humidity}}% humidity.',
@@ -136,6 +134,12 @@ const lastLogin = dict({
     ms: 'Log masuk terakhir: {{date}} pada {{time}}',
 })<{ date: `${number}-${number}-${number}`; time: `${number}:${number}` }>
 
+const { useT } = createT({
+    weather,
+    score,
+    lastLogin,
+})
+
 export const Page2 = () => {
     const { t, language, setLanguage } = useT()
     return (
@@ -150,14 +154,44 @@ export const Page2 = () => {
                 <option value="ja">Japanese</option>
                 <option value="ms">Malay</option>
             </select>
-            <p>{t(weather, { city: 'Kuala Lumpur', humidity: 80 })}</p>
-            <p>{t(score, { score: 87, total: 100 })}</p>
-            <p>{t(lastLogin, { date: '2024-04-24', time: '09:30' })}</p>
+            <p>{t('weather', { city: 'Kuala Lumpur', humidity: 80 })}</p>
+            <p>{t('score', { score: 87, total: 100 })}</p>
+            <p>{t('lastLogin', { date: '2024-04-24', time: '09:30' })}</p>
         </>
     )
 }
 ```
 
+## How It Works
+
+
+
+### One `kotori` instance per app
+
+`kotori` holds the language state. All `createT` calls share that state — changing the language anywhere rerenders everywhere.
+
+### One `createT` per page/component/feature
+
+Translations are colocated with the component that uses them. Bundlers naturally code-split them, so each page only loads what it needs.
+
+### Variables are inferred from string literals
+
+kotori parses `{{variable}}` at the type level. No separate type definitions needed — the string *is* the schema.
+
+```ts
+// primary string drives the contract
+const greeting = dict({ en: 'Hi {{name}}', zh: '你好 {{name}}' })
+//                                ^^^^^^ — inferred as required arg
+
+// secondary strings are validated against it
+const mismatch = dict({ en: 'Hi {{name}}', zh: '你好 {{other}}' })
+//                                                     ^^^^^^^ — compile error
+```
+
+### Custom argument types
+
+
+
 ## API
 
 ![how kotori works](image.webp) 
@@ -171,11 +205,15 @@ Creates a scoped i18n instance.
 | `primaryLanguageTag` | `AllTags` | The source language. Drives variable inference. |
 | `secondaryLanguageTags` | `AllTags[]` | Additional supported languages. |
 
-Returns `{ dict, useT, setLanguage }`.
+Returns `{ dict, createT, setLanguage }`.
 
 ### `dict(translations)<argsType?>`
 
-Defines a translation unit. Takes one string per language. Optionally takes a generic to narrow the interpolated variable types.
+Defines a translation unit. Takes one string per language
+
+```ts
+const time = dict({ en: '{{hour}}:{{minute}}' })
+```
 
 By default, variables are typed as `string | number`. Pass a generic to narrow them:
 
@@ -186,6 +224,10 @@ const time = dict({ en: '{{hour}}:{{minute}}' })<{
 }>
 ```
 
+### `createT(dicts)`
+
+Registers a set of dicts and returns `{ useT }`. Call once per page or feature module.
+
 ### `setLanguage(tag)`
 
 Updates the current language and rerenders all active `useT` consumers across all pages. Available directly on the `kotori` instance — useful for calling outside of React (route guards, axios interceptors, etc.).
@@ -196,7 +238,7 @@ React hook. Returns `{ t, language, setLanguage }`.
 
 | return | type | description |
 | --- | --- | --- |
-| `t(dict, args?)` | `string` | Returns the translated string for the current language. `args` is required if the string has variables, omitted if it doesn't. |
+| `t(key, args?)` | `string` | Returns the translated string for the current language. `args` is required if the string has variables, omitted if it doesn't. |
 | `language` | `primaryLanguageTag` \| `secondaryLanguageTags` | The current language tag as a reactive value. Updates when `setLanguage` is called. |
 | `setLanguage(tag)` | `void` | Updates the language and rerenders all active `useT` consumers. |
 
@@ -204,17 +246,8 @@ React hook. Returns `{ t, language, setLanguage }`.
 
 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-Hans`) are accepted and validated at the type level.
 
-## Roadmap
-
-- Auto detect locale from browser settings
-- Auto persist language selection to localStorage
-- Pluralization support
-- Gender support
-- Value formatting (date, number, currency)
-
 ## 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.
 
 *Kotori* (小鳥) means "small bird" in Japanese. No deeper relevance to the library — it just sounds nice.
-

package/dist/index.cjs

@@ -3,10 +3,10 @@ let react = require("react");
 //#region src/index.ts
 const kotori = (props) => {
 	const listeners = /* @__PURE__ */ new Set();
-	let language = props.primaryLanguageTag;
+	let languageTag = props.primaryLanguageTag;
 	const snapshots = /* @__PURE__ */ new Map();
 	const setLanguage = (tag) => {
-		language = tag;
+		languageTag = tag;
 		snapshots.forEach((snapshot, key) => {
 			snapshots.set(key, {
 				...snapshot,
@@ -23,19 +23,23 @@ const kotori = (props) => {
 			listeners.delete(listener);
 		};
 	};
-	const snapshot = {
-		language,
-		setLanguage,
-		t: (dict, ...args) => {
-			let locale = dict().translation[language] || "unable_to_load_translations";
-			for (const objKey in args[0]) locale = locale.replace(new RegExp(`\\{\\{\\s*${objKey}\\s*\\}\\}`, "g"), () => String(args[0]?.[objKey]));
-			return locale;
-		}
-	};
 	return {
 		setLanguage,
 		dict: (translation) => () => ({ translation }),
-		useT: () => (0, react.useSyncExternalStore)(subscribe, () => snapshot, () => snapshot)
+		createT: (dictCallbacks) => {
+			const s = Symbol();
+			const snapshot = {
+				language: languageTag,
+				setLanguage,
+				t: (key, ...args) => {
+					let locale = dictCallbacks[key]?.().translation[languageTag] || "unable_to_load_translations";
+					for (const objKey in args[0]) locale = locale.replace(new RegExp(`\\{\\{\\s*${objKey}\\s*\\}\\}`, "g"), () => String(args[0]?.[objKey]));
+					return locale;
+				}
+			};
+			snapshots.set(s, snapshot);
+			return { useT: () => (0, react.useSyncExternalStore)(subscribe, () => snapshots.get(s), () => snapshot) };
+		}
 	};
 };
 //#endregion

package/dist/index.d.cts

@@ -17,13 +17,15 @@ declare const kotori: <const PrimaryTag extends AllTags, const SecondaryTags ext
     translation: typeof translation;
     [_args]?: ArgsType;
   }>;
-  useT: () => {
-    language: PrimaryTag | SecondaryTags;
-    setLanguage: (tag: PrimaryTag | SecondaryTags) => void;
-    t: <DictCallback extends () => Readonly<{
-      translation: Record<PrimaryTag | SecondaryTags, string>;
-      [_args]?: Record<string, string | number>;
-    }>>(dict: DictCallback, ...args: keyof NonNullable<ReturnType<DictCallback>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<DictCallback>[typeof _args]>]) => string;
+  createT: <const DictCallbacks extends Record<string, () => Readonly<{
+    translation: Record<PrimaryTag | SecondaryTags, string>;
+    [_args]?: Record<string, string | number>;
+  }>>>(dictCallbacks: DictCallbacks) => {
+    useT: () => {
+      language: PrimaryTag | SecondaryTags;
+      setLanguage: (tag: PrimaryTag | SecondaryTags) => void;
+      t: <Key extends keyof DictCallbacks>(key: Key, ...args: keyof NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]>]) => string;
+    };
   };
 };
 //#endregion

package/dist/index.d.mts

@@ -17,13 +17,15 @@ declare const kotori: <const PrimaryTag extends AllTags, const SecondaryTags ext
     translation: typeof translation;
     [_args]?: ArgsType;
   }>;
-  useT: () => {
-    language: PrimaryTag | SecondaryTags;
-    setLanguage: (tag: PrimaryTag | SecondaryTags) => void;
-    t: <DictCallback extends () => Readonly<{
-      translation: Record<PrimaryTag | SecondaryTags, string>;
-      [_args]?: Record<string, string | number>;
-    }>>(dict: DictCallback, ...args: keyof NonNullable<ReturnType<DictCallback>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<DictCallback>[typeof _args]>]) => string;
+  createT: <const DictCallbacks extends Record<string, () => Readonly<{
+    translation: Record<PrimaryTag | SecondaryTags, string>;
+    [_args]?: Record<string, string | number>;
+  }>>>(dictCallbacks: DictCallbacks) => {
+    useT: () => {
+      language: PrimaryTag | SecondaryTags;
+      setLanguage: (tag: PrimaryTag | SecondaryTags) => void;
+      t: <Key extends keyof DictCallbacks>(key: Key, ...args: keyof NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]>]) => string;
+    };
   };
 };
 //#endregion

package/dist/index.mjs

@@ -2,10 +2,10 @@ import { useSyncExternalStore } from "react";
 //#region src/index.ts
 const kotori = (props) => {
 	const listeners = /* @__PURE__ */ new Set();
-	let language = props.primaryLanguageTag;
+	let languageTag = props.primaryLanguageTag;
 	const snapshots = /* @__PURE__ */ new Map();
 	const setLanguage = (tag) => {
-		language = tag;
+		languageTag = tag;
 		snapshots.forEach((snapshot, key) => {
 			snapshots.set(key, {
 				...snapshot,
@@ -22,19 +22,23 @@ const kotori = (props) => {
 			listeners.delete(listener);
 		};
 	};
-	const snapshot = {
-		language,
-		setLanguage,
-		t: (dict, ...args) => {
-			let locale = dict().translation[language] || "unable_to_load_translations";
-			for (const objKey in args[0]) locale = locale.replace(new RegExp(`\\{\\{\\s*${objKey}\\s*\\}\\}`, "g"), () => String(args[0]?.[objKey]));
-			return locale;
-		}
-	};
 	return {
 		setLanguage,
 		dict: (translation) => () => ({ translation }),
-		useT: () => useSyncExternalStore(subscribe, () => snapshot, () => snapshot)
+		createT: (dictCallbacks) => {
+			const s = Symbol();
+			const snapshot = {
+				language: languageTag,
+				setLanguage,
+				t: (key, ...args) => {
+					let locale = dictCallbacks[key]?.().translation[languageTag] || "unable_to_load_translations";
+					for (const objKey in args[0]) locale = locale.replace(new RegExp(`\\{\\{\\s*${objKey}\\s*\\}\\}`, "g"), () => String(args[0]?.[objKey]));
+					return locale;
+				}
+			};
+			snapshots.set(s, snapshot);
+			return { useT: () => useSyncExternalStore(subscribe, () => snapshots.get(s), () => snapshot) };
+		}
 	};
 };
 //#endregion

package/package.json

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