kotori 0.0.1 → 0.0.6

package/README.md

@@ -3,17 +3,28 @@
 Strongly-typed, modular i18n for React. Variables are inferred directly from your strings — no codegen, no JSON, no schema files.
 
 ```ts
-const intro = dict({ en: 'Hello {{name}}', zh: '你好 {{name}}' })
+const { dict } = kotori({
+    primaryLanguageTag: 'en',
+    secondaryLanguageTags: ['zh', 'ja', 'ms'],
+})
 
-t('intro', { name: 'John' }) // ✅ typed
-t('intro')                   // ❌ compile error: missing { name }
-t('intro', { nama: 'John' }) // ❌ compile error: unknown key 'nama'
+// ❌ compile error: missing japanese translation
+const intro = dict({ 
+    en: 'Hello {{name}}, is it {{time}} now?', // base string drives the type contract
+    zh: '你好，现在是 {{time}} 吗？',      // ❌ compile error: missing key 'nam' 
+    ms: 'Hai {{nam}}, adakah pukul {{time}} sekarang?'  // ❌ compile error: unknown key 'nam' 
+})<{name: string; time: `${number}:${number}`}> // optional: type your arguments, by default it's `Record<'name'|'time', string>` in this example
+
+t('intro', { name: 'John', time: '12:25' }) // ✅ 
+t('intro', { time: '12:25' })                   // ❌ compile error: missing { name }
+t('intro', { nama: 'John', time: '12:25' }) // ❌ compile error: unknown key 'nama'
+t('intro', { name: 'John', time: '12-00' }) // ❌ compile error: invalid format for 'time'
 ```
 
 - No codegen
 - No JSON
 - No dependencies
-- 0.31kb gzipped
+- 0.39kb gzipped
 - Modular and tree-shakeable
 - Language change in one page rerenders all pages
 - Variables typed and inferred from string literals
@@ -55,7 +66,7 @@ const time = dict({
     zh: '时间 {{time}}',
     ja: '時間 {{time}}',
     ms: 'waktu {{time}}',
-// type your arguments, by default it's `Record<string, string>`
+// optional: type your arguments, by default it's `Record<time, string>` in this example
 })<{ time: `${number}:${number}:${number}` }> 
 
 const { useTranslations } = createTranslations({
@@ -139,11 +150,13 @@ export const Page2 = () => {
 
 ## How It Works
 
+![how kotori works](image.png) 
+
 ### One `kotori` instance per app
 
 `kotori` holds the language state. All `createTranslations` calls share that state — changing the language anywhere rerenders everywhere.
 
-### One `createTranslations` per page/feature
+### One `createTranslations` 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.
 
@@ -179,16 +192,18 @@ const time = dict({ en: '{{hour}}:{{minute}}' })<{
 Creates a scoped i18n instance.
 
 | option | type | description |
-|---|---|---|
+| --- | --- | --- |
 | `primaryLanguageTag` | `AllTags` | The source language. Drives variable inference. |
 | `secondaryLanguageTags` | `AllTags[]` | Additional supported languages. |
 
 Returns `{ dict, createTranslations }`.
 
-### `dict(translations)(argsType?)`
+### `dict(translations)<argsType?>`
 
 Defines a translation unit. Takes one string per language. Optionally takes a generic to type the interpolated variables.
 
+Returns `() => { translations: Record<string, string> }`.
+
 ### `createTranslations(dicts)`
 
 Registers a set of dicts and returns `{ useTranslations }`. Call once per page or feature module.
@@ -198,7 +213,7 @@ Registers a set of dicts and returns `{ useTranslations }`. Call once per page o
 React hook. Returns `{ t, getLanguage, setLanguage }`.
 
 | return | description |
-|---|---|
+| --- | --- |
 | `t(key, args?)` | Returns the translated string for the current language. `args` is required if the string has variables, omitted if it doesn't. |
 | `getLanguage()` | Returns the current language tag. |
 | `setLanguage(tag)` | Updates the language and rerenders all active `useTranslations` consumers. |
@@ -211,4 +226,4 @@ kotori uses [BCP 47](https://www.iana.org/assignments/language-subtag-registry/l
 
 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.
+*Kotori* (小鳥) means "small bird" in Japanese. No deeper relevance to the library — it just sounds nice.

package/dist/index.cjs

@@ -1 +1,51 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`react`);const t=t=>{let n=new Set,r=t.primaryLanguageTag,i=new Map;return{dict:e=>()=>({translation:e}),createTranslations:t=>{let a=Symbol();return i.set(a,{getLanguage:()=>r,setLanguage:e=>{r=e,i.forEach((e,t)=>{i.set(t,{...e})}),n.forEach(e=>{e()})},t:(e,...n)=>{let i=t[e]?.().translation[r];if(i){for(let e in n[0])i=i.replace(RegExp(`\\{\\{\\s*${e}\\s*\\}\\}`,`g`),()=>String(n[0]?.[e]));return i}}}),{useTranslations:()=>(0,e.useSyncExternalStore)(e=>(n.add(e),()=>n.delete(e)),()=>i.get(a))}}}};exports.kotori=t;
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let react = require("react");
+
+//#region src/index.ts
+const kotori = (props) => {
+	const listeners = /* @__PURE__ */ new Set();
+	let languageTag = props.primaryLanguageTag;
+	const snapshots = /* @__PURE__ */ new Map();
+	const languageTagMethod = {
+		getLanguage: () => languageTag,
+		setLanguage: (tag) => {
+			languageTag = tag;
+			snapshots.forEach((snapshot, key) => {
+				snapshots.set(key, { ...snapshot });
+			});
+			listeners.forEach((listener) => {
+				listener();
+			});
+		}
+	};
+	return {
+		dict: (translation) => () => ({ translation }),
+		createTranslations: (dictCallbacks) => {
+			const s = Symbol();
+			let refCount = 0;
+			const snapshot = {
+				...languageTagMethod,
+				t: (key, ...args) => {
+					let locale = dictCallbacks[key]?.().translation[languageTag];
+					if (!locale) return;
+					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 { useTranslations: () => (0, react.useSyncExternalStore)((listener) => {
+				if (refCount === 0) snapshots.set(s, snapshot);
+				refCount++;
+				listeners.add(listener);
+				return () => {
+					refCount--;
+					if (refCount === 0) snapshots.delete(s);
+					listeners.delete(listener);
+				};
+			}, () => snapshots.get(s)) };
+		}
+	};
+};
+
+//#endregion
+exports.kotori = kotori;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 //#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/kotori.d.ts
+//#region src/index.d.ts
 type Tags = BCP47LanguageTagName;
 type SubTags = BCP47LanguageTagName extends `${infer SubTag}-${string}` ? SubTag : never;
 type AllTags = Tags | SubTags;
@@ -21,11 +21,11 @@ declare const kotori: <const PrimaryTag extends AllTags, const SecondaryTags ext
     [_args]?: Record<string, string | number>;
   }>>>(dictCallbacks: DictCallbacks) => {
     useTranslations: () => {
+      t: <Key extends keyof DictCallbacks>(key: Key, ...args: keyof NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]>]) => Record<PrimaryTag | SecondaryTags, string>[PrimaryTag | SecondaryTags] | undefined;
       getLanguage: () => 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]>]) => Record<PrimaryTag | SecondaryTags, string>[PrimaryTag | SecondaryTags] | undefined;
     };
   };
 };
 //#endregion
-export { AllTags, ExtractVariables, SubTags, Tags, kotori };
+export { AllTags, SubTags, Tags, kotori };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 //#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/kotori.d.ts
+//#region src/index.d.ts
 type Tags = BCP47LanguageTagName;
 type SubTags = BCP47LanguageTagName extends `${infer SubTag}-${string}` ? SubTag : never;
 type AllTags = Tags | SubTags;
@@ -21,11 +21,11 @@ declare const kotori: <const PrimaryTag extends AllTags, const SecondaryTags ext
     [_args]?: Record<string, string | number>;
   }>>>(dictCallbacks: DictCallbacks) => {
     useTranslations: () => {
+      t: <Key extends keyof DictCallbacks>(key: Key, ...args: keyof NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]> extends never ? [] : [NonNullable<ReturnType<DictCallbacks[Key]>[typeof _args]>]) => Record<PrimaryTag | SecondaryTags, string>[PrimaryTag | SecondaryTags] | undefined;
       getLanguage: () => 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]>]) => Record<PrimaryTag | SecondaryTags, string>[PrimaryTag | SecondaryTags] | undefined;
     };
   };
 };
 //#endregion
-export { AllTags, ExtractVariables, SubTags, Tags, kotori };
+export { AllTags, SubTags, Tags, kotori };

package/dist/index.mjs

@@ -1 +1,50 @@
-import{useSyncExternalStore as e}from"react";const t=t=>{let n=new Set,r=t.primaryLanguageTag,i=new Map;return{dict:e=>()=>({translation:e}),createTranslations:t=>{let a=Symbol();return i.set(a,{getLanguage:()=>r,setLanguage:e=>{r=e,i.forEach((e,t)=>{i.set(t,{...e})}),n.forEach(e=>{e()})},t:(e,...n)=>{let i=t[e]?.().translation[r];if(i){for(let e in n[0])i=i.replace(RegExp(`\\{\\{\\s*${e}\\s*\\}\\}`,`g`),()=>String(n[0]?.[e]));return i}}}),{useTranslations:()=>e(e=>(n.add(e),()=>n.delete(e)),()=>i.get(a))}}}};export{t as kotori};
+import { useSyncExternalStore } from "react";
+
+//#region src/index.ts
+const kotori = (props) => {
+	const listeners = /* @__PURE__ */ new Set();
+	let languageTag = props.primaryLanguageTag;
+	const snapshots = /* @__PURE__ */ new Map();
+	const languageTagMethod = {
+		getLanguage: () => languageTag,
+		setLanguage: (tag) => {
+			languageTag = tag;
+			snapshots.forEach((snapshot, key) => {
+				snapshots.set(key, { ...snapshot });
+			});
+			listeners.forEach((listener) => {
+				listener();
+			});
+		}
+	};
+	return {
+		dict: (translation) => () => ({ translation }),
+		createTranslations: (dictCallbacks) => {
+			const s = Symbol();
+			let refCount = 0;
+			const snapshot = {
+				...languageTagMethod,
+				t: (key, ...args) => {
+					let locale = dictCallbacks[key]?.().translation[languageTag];
+					if (!locale) return;
+					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 { useTranslations: () => useSyncExternalStore((listener) => {
+				if (refCount === 0) snapshots.set(s, snapshot);
+				refCount++;
+				listeners.add(listener);
+				return () => {
+					refCount--;
+					if (refCount === 0) snapshots.delete(s);
+					listeners.delete(listener);
+				};
+			}, () => snapshots.get(s)) };
+		}
+	};
+};
+
+//#endregion
+export { kotori };

package/package.json

@@ -1,65 +1,72 @@
-{
-	"name": "kotori",
-	"description": "Strongly-typed and composable internationalization library for React",
-	"version": "0.0.1",
-	"scripts": {
-		"setup": "rm -rf node_modules && npm i && git init && husky",
-		"prepublishOnly": "npm run build",
-		"build": "tsdown",
-		"test": "vitest",
-		"lint": "npx @biomejs/biome check --write",
-		"dev": "vite --host"
-	},
-	"files": [
-		"dist"
-	],
-	"lint-staged": {
-		"*": [
-			"npm run lint"
-		]
-	},
-	"type": "module",
-	"main": "./dist/index.cjs",
-	"types": "./dist/index.d.cts",
-	"exports": {
-		".": {
-			"require": {
-				"types": "./dist/index.d.cts",
-				"default": "./dist/index.cjs"
-			},
-			"import": {
-				"types": "./dist/index.d.mts",
-				"default": "./dist/index.mjs"
-			}
-		}
-	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.4.12",
-		"@types/node": "^25.6.0",
-		"@types/react": "^19.2.14",
-		"@types/react-dom": "^19.2.3",
-		"@vitejs/plugin-react": "^6.0.1",
-		"@vitest/coverage-v8": "^4.1.5",
-		"bcp47-language-tags": "^1.1.0",
-		"husky": "^9.1.7",
-		"lint-staged": "^16.4.0",
-		"react": "^19.2.5",
-		"react-dom": "^19.2.5",
-		"tsdown": "^0.21.10",
-		"tsx": "^4.21.0",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.5"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/tylim88/kotori.git"
-	},
-	"bugs": {
-		"url": "https://github.com/tylim88/kotori/issues"
-	},
-	"author": "tylim88",
-	"license": "MIT",
-	"peerDependencies": {
-		"react": ">=19.2.5"
-	}
-}
+{
+	"name": "kotori",
+	"description": "Strongly-typed and composable internationalization library for React",
+	"version": "0.0.6",
+	"scripts": {
+		"setup": "rm -rf node_modules && npm i && git init && husky",
+		"prepublishOnly": "npm run build",
+		"build": "tsdown",
+		"test": "vitest",
+		"lint": "npx @biomejs/biome check --write",
+		"dev": "vite --host"
+	},
+	"files": [
+		"dist"
+	],
+	"lint-staged": {
+		"*": [
+			"npm run lint"
+		]
+	},
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"types": "./dist/index.d.cts",
+	"exports": {
+		".": {
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			},
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			}
+		}
+	},
+	"keywords": [
+		"i18n",
+		"internationalization",
+		"react",
+		"typescript",
+		"strongly-typed"
+	],
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.12",
+		"@types/node": "^25.6.0",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"@vitejs/plugin-react": "^6.0.1",
+		"@vitest/coverage-v8": "^4.1.5",
+		"bcp47-language-tags": "^1.1.0",
+		"husky": "^9.1.7",
+		"lint-staged": "^16.4.0",
+		"react": "^19.2.5",
+		"react-dom": "^19.2.5",
+		"tsdown": "^0.21.10",
+		"tsx": "^4.21.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.5"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tylim88/kotori.git"
+	},
+	"bugs": {
+		"url": "https://github.com/tylim88/kotori/issues"
+	},
+	"author": "tylim88",
+	"license": "MIT",
+	"peerDependencies": {
+		"react": ">=19.2.5"
+	}
+}