kotori 0.1.6 → 1.0.0

package/README.md

@@ -12,19 +12,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' }) 
 ```
@@ -33,11 +40,11 @@ t('intro', { name: 'John', time: '12-00' })
 - No JSON
 - No dependencies
 - No build step
-- 0.38kb gzipped
+- 0.34kb 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,7 +61,7 @@ npm i kotori
 ```ts
 import { kotori } from './kotori'
 
-export const { createTranslations, dict, setLanguage } = kotori({
+export const { useT, dict, setLanguage } = kotori({
     primaryLanguageTag: 'en',
     secondaryLanguageTags: ['zh', 'ja', 'ms'],
 })
@@ -63,7 +70,7 @@ export const { createTranslations, dict, setLanguage } = kotori({
 **page1.tsx**
 
 ```tsx
-import { createTranslations, dict } from './utils'
+import { useT, dict } from './utils'
 
 const intro = dict({
     en: 'my name is {{name}}, I am {{age}} years old.',
@@ -80,13 +87,8 @@ const time = dict({
 // optional: type your arguments, by default it's `Record<'time', string | number>` in this example
 })<{ time: `${number}:${number}:${number}` }> 
 
-const { useTranslations } = createTranslations({
-    intro,
-    time,
-})
-
 export const Page1 = () => {
-    const { t, language, setLanguage } = useTranslations()
+    const { t, language, setLanguage } = useT()
     return (
         <>
             <select
@@ -109,7 +111,7 @@ export const Page1 = () => {
 **page2.tsx**
 
 ```tsx
-import { createTranslations, dict } from './utils'
+import { useT, dict } from './utils'
 
 const weather = dict({
     en: 'The weather in {{city}} has {{humidity}}% humidity.',
@@ -132,14 +134,8 @@ const lastLogin = dict({
     ms: 'Log masuk terakhir: {{date}} pada {{time}}',
 })<{ date: `${number}-${number}-${number}`; time: `${number}:${number}` }>
 
-const { useTranslations } = createTranslations({
-    weather,
-    score,
-    lastLogin,
-})
-
 export const Page2 = () => {
-    const { t, language, setLanguage } = useTranslations()
+    const { t, language, setLanguage } = useT()
     return (
         <>
             <select
@@ -152,53 +148,18 @@ 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
+## API
 
 ![how kotori works](image.webp) 
 
-### 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/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
-
-By default, variables are typed as `string | number`. Pass a generic to narrow them:
-
-```ts
-const time = dict({ en: '{{hour}}:{{minute}}' })<{
-    hour: number
-    minute: number
-}>
-```
-
-## API
-
 ### `kotori(options)`
 
 Creates a scoped i18n instance.
@@ -208,36 +169,50 @@ Creates a scoped i18n instance.
 | `primaryLanguageTag` | `AllTags` | The source language. Drives variable inference. |
 | `secondaryLanguageTags` | `AllTags[]` | Additional supported languages. |
 
-Returns `{ dict, createTranslations, setLanguage }`.
+Returns `{ dict, useT, setLanguage }`.
 
 ### `dict(translations)<argsType?>`
 
 Defines a translation unit. Takes one string per language. Optionally takes a generic to narrow the interpolated variable types.
 
-### `createTranslations(dicts)`
+By default, variables are typed as `string | number`. Pass a generic to narrow them:
 
-Registers a set of dicts and returns `{ useTranslations }`. Call once per page or feature module.
+```ts
+const time = dict({ en: '{{hour}}:{{minute}}' })<{
+    hour: number
+    minute: number
+}>
+```
 
 ### `setLanguage(tag)`
 
-Updates the current language and rerenders all active `useTranslations` consumers across all pages. Available directly on the `kotori` instance — useful for calling outside of React (route guards, axios interceptors, etc.).
+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.).
 
-### `useTranslations()`
+### `useT()`
 
 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. |
-| `language` | `WorkingTags` | The current language tag as a reactive value. Updates when `setLanguage` is called. |
-| `setLanguage(tag)` | `void` | Updates the language and rerenders all active `useTranslations` consumers. |
+| `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. |
 
 ## 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-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 languageTag = props.primaryLanguageTag;
+	let language = props.primaryLanguageTag;
 	const snapshots = /* @__PURE__ */ new Map();
 	const setLanguage = (tag) => {
-		languageTag = tag;
+		language = tag;
 		snapshots.forEach((snapshot, key) => {
 			snapshots.set(key, {
 				...snapshot,
@@ -23,23 +23,19 @@ 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 }),
-		createTranslations: (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 { useTranslations: () => (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;
   }>;
-  createTranslations: <const DictCallbacks extends Record<string, () => Readonly<{
-    translation: Record<PrimaryTag | SecondaryTags, string>;
-    [_args]?: Record<string, string | number>;
-  }>>>(dictCallbacks: DictCallbacks) => {
-    useTranslations: () => {
-      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;
   }>;
-  createTranslations: <const DictCallbacks extends Record<string, () => Readonly<{
-    translation: Record<PrimaryTag | SecondaryTags, string>;
-    [_args]?: Record<string, string | number>;
-  }>>>(dictCallbacks: DictCallbacks) => {
-    useTranslations: () => {
-      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,10 +2,10 @@ import { useSyncExternalStore } from "react";
 //#region src/index.ts
 const kotori = (props) => {
 	const listeners = /* @__PURE__ */ new Set();
-	let languageTag = props.primaryLanguageTag;
+	let language = props.primaryLanguageTag;
 	const snapshots = /* @__PURE__ */ new Map();
 	const setLanguage = (tag) => {
-		languageTag = tag;
+		language = tag;
 		snapshots.forEach((snapshot, key) => {
 			snapshots.set(key, {
 				...snapshot,
@@ -22,23 +22,19 @@ 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 }),
-		createTranslations: (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 { useTranslations: () => useSyncExternalStore(subscribe, () => snapshots.get(s), () => snapshot) };
-		}
+		useT: () => useSyncExternalStore(subscribe, () => snapshot, () => snapshot)
 	};
 };
 //#endregion

package/package.json

@@ -1,73 +1,73 @@
-{
-	"name": "kotori",
-	"description": "Strongly-typed and composable internationalization library for React",
-	"version": "0.1.6",
-	"scripts": {
-		"setup": "rm -rf node_modules && npm i && git init && husky",
-		"prepublishOnly": "npm i && npx tsc && npm run build",
-		"build": "tsdown",
-		"size": "tsdown --minify",
-		"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"
-	}
-}
+{
+	"name": "kotori",
+	"description": "Strongly-typed and composable internationalization library for React",
+	"version": "1.0.0",
+	"scripts": {
+		"setup": "rm -rf node_modules && npm i && git init && husky",
+		"prepublishOnly": "npm i && npx tsc && npm run build",
+		"build": "tsdown",
+		"size": "tsdown --minify",
+		"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"
+	}
+}