kotori 2.0.2 → 3.0.1

package/README.md

@@ -14,19 +14,26 @@ 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' }) 
 ```
@@ -35,11 +42,11 @@ t('intro', { name: 'John', time: '12-00' })
 - No JSON
 - No dependencies
 - No build step
-- 0.38kb gzipped
+- 0.33kb gzipped
 - Modular and tree-shakeable
 - Language change in one page rerenders all pages
-- Translation keys are typed — no more string typos
-- Variables typed and inferred from string literals
+- Variables typed and inferred from string literals — no more string typos
+- maximum type safety with minimum types
 
 Demo: <https://stackblitz.com/edit/vitejs-vite-nyxwmhre?file=src%2FApp.tsx>
 
@@ -54,9 +61,9 @@ npm i kotori
 **utils.ts**
 
 ```ts
-import { kotori } from './kotori'
+import { kotori } from 'kotori'
 
-export const { createT, dict, setLanguage } = kotori({
+export const { useT, dict, setLanguage } = kotori({
     primaryLanguageTag: 'en',
     secondaryLanguageTags: ['zh', 'ja', 'ms'],
 })
@@ -65,7 +72,7 @@ export const { createT, dict, setLanguage } = kotori({
 **page1.tsx**
 
 ```tsx
-import { createT, dict } from './utils'
+import { useT, dict } from './utils'
 
 const intro = dict({
     en: 'my name is {{name}}, I am {{age}} years old.',
@@ -82,11 +89,6 @@ 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 (
@@ -111,7 +113,7 @@ export const Page1 = () => {
 **page2.tsx**
 
 ```tsx
-import { createT, dict } from './utils'
+import { useT, dict } from './utils'
 
 const weather = dict({
     en: 'The weather in {{city}} has {{humidity}}% humidity.',
@@ -134,12 +136,6 @@ 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 (
@@ -154,9 +150,9 @@ 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>
         </>
     )
 }
@@ -164,22 +160,31 @@ export const Page2 = () => {
 
 ## API
 
-![API](image.webp) 
+![how kotori works](image.webp) 
 
 ### `kotori(options)`
 
 Creates a scoped i18n instance.
 
+```ts
+import { kotori } from 'kotori'
+
+export const { useT, dict, setLanguage } = kotori({
+    primaryLanguageTag: 'en',
+    secondaryLanguageTags: ['zh', 'ja', 'ms'],
+})
+```
+
 | option | type | description |
 | --- | --- | --- |
-| `primaryLanguageTag` | `AllTags` | The source language. Drives variable inference. |
-| `secondaryLanguageTags` | `AllTags[]` | Additional supported languages. |
+| `primaryLanguageTag` | `BCP47LanguageTag` | The source language. Drives variable inference. |
+| `secondaryLanguageTags` | `BCP47LanguageTag[]` | Additional supported languages. |
 
-Returns `{ dict, createT, setLanguage }`.
+Returns `{ dict, useT, setLanguage }`.
 
 ### `dict(translations)<argsType?>`
 
-Defines a translation unit. Takes one string per language
+Defines a translation unit. Takes one string per language.
 
 ```ts
 const time = dict({ en: '{{hour}}:{{minute}}' })
@@ -194,10 +199,6 @@ 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.).
@@ -208,7 +209,7 @@ React hook. Returns `{ t, language, setLanguage }`.
 
 | return | type | description |
 | --- | --- | --- |
-| `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. |
+| `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. |
 | `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. |
 
@@ -216,8 +217,17 @@ 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,16 +3,13 @@ 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();
+	let language = props.primaryLanguageTag;
 	const setLanguage = (tag) => {
-		languageTag = tag;
-		snapshots.forEach((snapshot, key) => {
-			snapshots.set(key, {
-				...snapshot,
-				language: tag
-			});
-		});
+		language = tag;
+		snapshot = {
+			...snapshot,
+			language
+		};
 		listeners.forEach((listener) => {
 			listener();
 		});
@@ -23,23 +20,19 @@ const kotori = (props) => {
 			listeners.delete(listener);
 		};
 	};
+	let 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 }),
-		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) };
-		}
+		useT: () => (0, react.useSyncExternalStore)(subscribe, () => snapshot, () => snapshot)
 	};
 };
 //#endregion

package/dist/index.d.cts

@@ -17,15 +17,13 @@ declare const kotori: <const PrimaryTag extends AllTags, const SecondaryTags ext
     translation: typeof translation;
     [_args]?: ArgsType;
   }>;
-  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;
-    };
+  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;
   };
 };
 //#endregion

package/dist/index.d.mts

@@ -17,15 +17,13 @@ declare const kotori: <const PrimaryTag extends AllTags, const SecondaryTags ext
     translation: typeof translation;
     [_args]?: ArgsType;
   }>;
-  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;
-    };
+  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;
   };
 };
 //#endregion

package/dist/index.mjs

@@ -2,16 +2,13 @@ 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();
+	let language = props.primaryLanguageTag;
 	const setLanguage = (tag) => {
-		languageTag = tag;
-		snapshots.forEach((snapshot, key) => {
-			snapshots.set(key, {
-				...snapshot,
-				language: tag
-			});
-		});
+		language = tag;
+		snapshot = {
+			...snapshot,
+			language
+		};
 		listeners.forEach((listener) => {
 			listener();
 		});
@@ -22,23 +19,19 @@ const kotori = (props) => {
 			listeners.delete(listener);
 		};
 	};
+	let 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 }),
-		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) };
-		}
+		useT: () => useSyncExternalStore(subscribe, () => snapshot, () => snapshot)
 	};
 };
 //#endregion

package/package.json

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