![\"kotori](\"logo.webp\")
\r\n\r\n \r\n
\r\n ![\"NPM](\"https://img.shields.io/npm/v/kotori?color=blue\")
![\"Coverage\"](\"https://img.shields.io/codecov/c/github/tylim88/Kotori?branch=main\")
![\"Bundle](\"https://img.shields.io/badge/bundle%20size-0.28kB-emerald\"){kind=icon}
![\"License\"](\"https://img.shields.io/github/license/tylim88/Kotori?color=blue\")
![\"Dependencies\"](\"https://img.shields.io/badge/dependencies-0-success\"){kind=icon}
![\"Snyk](\"https://snyk.io/test/github/tylim88/Kotori/badge.svg\"){kind=icon}
\r\n \r\n
\r\n🕊️ Kotori is a zero-config, fully type-safe, and modular internationalization library for React that compiles down to just 0.28kB. No JSON, no external CLI tools, no codegen—just live type inference from your strings.\r\n
\r\n\r\n```ts\r\nconst { d, useT } = kotori({\r\n primary: 'en',\r\n secondaries: ['zh', 'ja', 'ms'],\r\n})\r\n\r\n// ❌ TypeScript error: missing japanese translation\r\nconst intro = d({ \r\n // ⭐ base string drives the type contract\r\n en: 'Hello {{name}}, is it {{time}} now?', \r\n\r\n // ❌ TypeScript error: missing key 'name' \r\n zh: '你好，现在是 {{time}} 吗？',\r\n\r\n // ❌ TypeScript error: unknown key 'nam' \r\n ms: 'Hai {{nam}}, adakah pukul {{time}} sekarang?' \r\n\r\n// optional: type your arguments, by default it's `Record<'name'|'time', string | number>` in this example\r\n})<{name: string; time: `${number}:${number}`}> \r\n\r\nconst Component = () => {\r\n const { t } = useT()\r\n\r\n // ✅ Works\r\n t(intro, { name: 'John', time: '12:25' }) \r\n\r\n // ❌ TypeScript error: missing { name }\r\n t(intro, { time: '12:25' })\r\n\r\n // ❌ TypeScript error: unknown key 'nama' \r\n t(intro, { nama: 'John', time: '12:25' }) \r\n\r\n // ❌ TypeScript error: invalid format for 'time'\r\n t(intro, { name: 'John', time: '12-00' }) \r\n}\r\n```\r\n\r\n- No codegen\r\n- No JSON\r\n- No dependencies\r\n- No build step\r\n- 0.28kB minified and gzipped\r\n- Modular and tree-shakeable\r\n- Language change in one page rerenders all pages\r\n- Variables typed and inferred from string literals — no more string typos\r\n- Maximum type safety with minimum types\r\n\r\nDemo:{t(intro, { name: 'John', age: 30 })}
\r\n{t(time, { time: '12:00:00' })}
\r\n \r\n )\r\n}\r\n```\r\n\r\n### page2.tsx\r\n\r\n```tsx\r\nimport { useT, d } from './locales'\r\n\r\n// you can also define dicts in the same file as your components, it's up to you\r\nconst weather = d({\r\n en: 'The weather in {{city}} has {{humidity}}% humidity.',\r\n zh: '{{city}}的天气湿度为{{humidity}}%。',\r\n ja: '{{city}}の湿度は{{humidity}}%です。',\r\n ms: 'Cuaca di {{city}} mempunyai kelembapan {{humidity}}%.',\r\n})<{ city: string; humidity: number }>\r\n\r\nconst lastLogin = d({\r\n en: 'Last login: {{date}} at {{time}}',\r\n zh: '上次登录：{{date}} {{time}}',\r\n ja: '最終ログイン：{{date}} {{time}}',\r\n ms: 'Log masuk terakhir: {{date}} pada {{time}}',\r\n})<{ date: `${number}-${number}-${number}`; time: `${number}:${number}` }>\r\n\r\nexport const Page2 = () => {\r\n\r\n const { t } = useT()\r\n\r\n return (\r\n <>\r\n{t(weather, { city: 'Kuala Lumpur', humidity: 80 })}
\r\n{t(lastLogin, { date: '2024-04-24', time: '09:30' })}
\r\n \r\n )\r\n}\r\n```\r\n\r\n## API\r\n\r\n \r\n\r\n### `kotori(options)` (0.28kB)\r\n\r\nCreates a scoped i18n instance.\r\n\r\n```ts\r\nimport { kotori } from 'kotori'\r\n\r\nexport const { useT, d, setLanguage } = kotori({\r\n primary: 'en',\r\n secondaries: ['zh', 'ja', 'ms'],\r\n})\r\n```\r\n\r\n| option | type | description |\r\n| --- | --- | --- |\r\n| `primary` | `BCP47LanguageTagWithSubtag` | The source language. Drives variable inference. |\r\n| `secondaries` | `Exclude{t(intro, { name: 'John', age: 30 })}
\r\n )\r\n}\r\n```\r\n\r\n### `detectLanguage(instance, options?)` (0.12kB with Kotori or 0.2kB standalone)\r\n\r\nDetects the user's preferred language from browser settings and sets it on the kotori instance. Iterates through the user's full language preference list in order, stopping at the first match.\r\n\r\n```ts\r\nimport { detectLanguage } from 'kotori'\r\nimport { kotori } from 'kotori'\r\n\r\nconst i18n = kotori({\r\n primary: 'en',\r\n secondaries: ['zh', 'ja', 'ms'],\r\n})\r\n\r\ndetectLanguage(i18n)\r\n\r\nexport const { useT, d, setLanguage } = i18n\r\n```\r\n\r\n| option | type | default | description |\r\n| --- | --- | --- | --- |\r\n| `fallbackToSubtag` | `boolean` | `true` | If no exact match is found (e.g. `'zh-CN'`), fall back to the subtag (e.g. `'zh'`). |\r\n\r\n```ts\r\n// browser reports: ['zh-CN', 'en-US']\r\n// declared languages: ['en', 'zh', 'ja', 'ms']\r\n\r\ndetectLanguage(i18n)\r\n// 'zh-CN' → no exact match → subtag 'zh' → match → setLanguage('zh') ✅\r\n\r\ndetectLanguage(i18n, { fallbackToSubtag: false })\r\n// 'zh-CN' → no exact match → 'en-US' → no exact match → no-op, stays 'en'\r\n```\r\n\r\n`detectLanguage` also works with non-kotori instances. Any object with a `setLanguage` callback and a `config` object satisfies the interface:\r\n\r\n```ts\r\ndetectLanguage({\r\n setLanguage: (lang: 'en' | 'zh') => mySetLang(lang),\r\n config: { primary: 'en', secondaries: ['zh'] },\r\n})\r\n```\r\n\r\n## Language Tags\r\n\r\nkotori uses [BCP 47](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) language tags. The type `BCP47LanguageTagWithSubtag` accepts both subtags (`en`, `zh`) and full tags (`en-US`, `zh-CN`), and is validated at the type level.\r\n\r\n```ts\r\nkotori({ primary: 'en', secondaries: ['zh', 'ms-MY'] }) // ✅\r\nkotori({ primary: 'klingon', secondaries: ['zh'] }) // ❌ compile error\r\n```\r\n\r\n## Tips\r\n\r\n- 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 files and hand it to an AI to translate.\r\n- If your supported languages are fixed, consider splitting dicts by page or component. This keeps translations close to the code that uses them and makes them easier to maintain.\r\n- For large or rarely used components, you can also reduce your bundle size by dynamically importing them only when they are needed on the page.\r\n\r\n## Roadmap\r\n\r\n- ✅ Auto detect locale from browser settings\r\n- Auto persist language selection to localStorage\r\n- Pluralization support\r\n- Gender support\r\n- Value formatting (date, number, currency)\r\n\r\n## Trivial\r\n\r\nThere 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.\r\n\r\n*Kotori* (小鳥) means \"small bird\" in Japanese. No deeper relevance to the library — it just sounds nice.","readmeFilename":"README.md"}