{"id":"discontentdino/localize","name":"localize","scope":"discontentdino","platform":"roblox","description":"Internationalization (i18n) and localization with automatic pluralization for Luau and TS. An i18next-style translation library for Roblox games.","version":"2.0.0","latest":"2.0.0","versions":["2.0.0"],"license":"ISC","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"c4abfc75334268c3be6e59dfb77618f653163ce54301d4c65d14c84cbb46bf56","likes":0,"downloads":0,"install":"forest install discontentdino/localize","url":"https://forest.dev/p/roblox/discontentdino/localize","files":"https://api.forest.dev/ai/package/roblox/discontentdino/localize/files","readme":"# `localize`\n\n[![npm version](https://img.shields.io/npm/v/@rbxts/localize)](https://www.npmjs.com/package/@rbxts/localize)\n[![npm downloads](https://img.shields.io/npm/dm/@rbxts/localize)](https://www.npmjs.com/package/@rbxts/localize)\n[![license](https://img.shields.io/npm/l/@rbxts/localize)](https://github.com/DiscontentDino/localize/blob/main/LICENSE.md)\n\n`localize` is a runtime internationalization (i18n) and localization library for\nRoblox, inspired by i18next. Define your translations as data and resolve them\nat runtime!\n\n## Why `localize`\n\nRoblox's automatic translation renders the same string inconsistently within a\nsingle language.\n\nExample: when localizing the string \"Spectating {username}\", it sometimes\nrenders as \"正在观看 Player A\", \"正在观战 Player B\", or worse, just leaves it in\nEnglish. This is because Roblox's automatic translation solution isn't aware of\nparameters, so it can't consistently translate the same string with different\nparameters.\n\n## Quick Start\n\n### Installation\n\nWith Wally:\n\n```toml\n[dependencies]\nlocalize = \"discontentdino/localize@2.0.0\"\n```\n\nWith roblox-ts:\n\n```bash\npnpm add @rbxts/localize\n```\n\n### Usage\n\nTranslations come from a `backend`. Its `read` function returns the translations\nfor a language and namespace, and it may yield.\n\n```lua\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal Localize = require(ReplicatedStorage.Packages.localize)\n\nlocal translations = {\n    en_US = {\n        translation = {\n            greeting = \"Hello {{name}}\",\n            apples_one = \"You have {{count}} apple\",\n            apples_other = \"You have {{count}} apples\",\n            place_ordinal_one = \"You came in {{count}}st place\",\n            place_ordinal_two = \"You came in {{count}}nd place\",\n            place_ordinal_few = \"You came in {{count}}rd place\",\n            place_ordinal_other = \"You came in {{count}}th place\",\n            coins_one = \"{{count, number(notation: compact)}} coin\",\n            coins_other = \"{{count, number(notation: compact)}} coins\",\n        },\n        shop = { buy = \"Buy\" },\n    },\n    zh_CN = {\n        translation = {\n            greeting = \"你好，{{name}}\",\n            apples_other = \"你有{{count}}个苹果\",\n        },\n        shop = { buy = \"购买\" },\n    },\n}\n\nlocal i18n = Localize.new({\n    language = \"en_US\",\n    fallbackLanguage = \"en_US\",\n    namespaces = { \"translation\", \"shop\" },\n    backend = {\n        read = function(language, namespace)\n            return translations[language][namespace]\n        end,\n    },\n})\n\ni18n:t(\"greeting\", { name = \"Jo\" }) -- Hello Jo\n```\n\nThe same thing in roblox-ts:\n\n```ts\nimport { Localize } from \"@rbxts/localize\";\n\nconst i18n = new Localize({\n    language: \"en_US\",\n    backend: {\n        read: () => ({ greeting: \"Hello {{name}}\" }),\n    },\n});\n\nprint(i18n.t(\"greeting\", { name: \"Jo\" })); // Hello Jo\n```\n\n## Plurals\n\nPass `count` to select a plural form. Keys end in a CLDR category: `_zero`,\n`_one`, `_two`, `_few`, `_many` or `_other`. Each language only needs the\ncategories it uses. Change the `_` with the `pluralSeparator` option.\n\n```lua\ni18n:t(\"apples\", { count = 1 }) -- You have 1 apple\ni18n:t(\"apples\", { count = 2 }) -- You have 2 apples\n```\n\nA lookup tries `key_<category>`, then `key_other`, then `key`, and then the same\nin the fallback language using that language's rules.\n\nFor ordinals, pass `ordinal = true` and use `_ordinal_<category>` keys:\n\n```lua\ni18n:t(\"place\", { count = 1, ordinal = true }) -- You came in 1st place\ni18n:t(\"place\", { count = 2, ordinal = true }) -- You came in 2nd place\ni18n:t(\"place\", { count = 3, ordinal = true }) -- You came in 3rd place\ni18n:t(\"place\", { count = 11, ordinal = true }) -- You came in 11th place\n```\n\n## Namespaces\n\n`:` selects a namespace, and keys without one use the default namespace. The key\nitself is returned when the key is missing.\n\n```lua\ni18n:t(\"shop:buy\") -- Buy\ni18n:t(\"missing\") -- missing\n```\n\nChange the `:` with the `namespaceSeparator` option, or set it to `false` to\nturn it off.\n\n## Typed Keys\n\nIn roblox-ts, pass your translations as a type argument to check the keys of\n`t`. Keys with only `_ordinal_` forms then need `ordinal: true`.\n\n```ts\nimport type shop from \"./locales/en_US/shop.json\";\nimport type translation from \"./locales/en_US/translation.json\";\n\nconst i18n = new Localize<{\n    translations: { translation: typeof translation; shop: typeof shop };\n}>({\n    language: \"en_US\",\n    namespaces: [\"translation\", \"shop\"],\n    backend,\n});\n\ni18n.t(\"apples\", { count: 2 }); // ok\ni18n.t(\"place\", { count: 1, ordinal: true }); // ok\ni18n.t(\"shop:buy\"); // ok\ni18n.t(\"missing\"); // error\ni18n.t(\"place\"); // error\n```\n\nThe type argument also takes `defaultNamespace`, `namespaceSeparator` and\n`pluralSeparator`. When it sets one, the options must set it to the same value.\n\n## Interpolation\n\n`{{name}}` inserts a variable, and a missing variable stays as written. Use\n`\\{{` for a literal `{{` and `\\\\` for a literal backslash.\n\n## Number Formatting\n\nFormat a number for the current language:\n\n```lua\ni18n:formatNumber(1234.5) -- 1,234.5\ni18n:formatNumber(1500000, { notation = \"compact\" }) -- 1.5M\ni18n:formatNumber(1500, { notation = \"compact\", compactDisplay = \"long\" })\n    -- 1.5 thousand\ni18n:formatNumber(2, { minimumFractionDigits = 2 }) -- 2.00\n```\n\nOr format it inside a translation with `{{variable, number}}`. Separate multiple\noptions with `;`.\n\n```lua\ni18n:t(\"coins\", { count = 1 }) -- 1 coin\ni18n:t(\"coins\", { count = 1500 }) -- 1.5K coins\n```\n\nThe options are `notation`, `compactDisplay`, `minimumFractionDigits`,\n`maximumFractionDigits` and `useGrouping`.\n\n## Languages\n\nChange language with `changeLanguage`. It yields until the backend has loaded\nthe language.\n\n```lua\ni18n:changeLanguage(\"zh_CN\")\ni18n:t(\"apples\", { count = 1 }) -- 你有1个苹果\ni18n:formatNumber(15000, { notation = \"compact\" }) -- 1.5万\n```\n\n`LanguageChanged` fires after the language changes, so you can refresh your UI:\n\n```lua\nlocal connection = i18n.LanguageChanged:Connect(function(language)\n    print(language)\nend)\n\nconnection:Disconnect()\n```\n\nLanguages use codes like `en_US`, not Roblox's `LocaleId`. Convert a `LocaleId`\nwith `robloxLocaleIdToLanguageCode`, which returns `nil` if it isn't supported:\n\n```lua\nlocal LocalizationService = game:GetService(\"LocalizationService\")\n\nlocal localeId = LocalizationService.RobloxLocaleId\ni18n:changeLanguage(Localize.robloxLocaleIdToLanguageCode(localeId) or \"en_US\")\n```\n\nAdd namespaces later with `loadNamespaces`, or preload languages with\n`loadLanguages`.\n\n## Supported Languages\n\n| Language | Code | Roblox `LocaleId` |\n| --- | --- | --- |\n| German | `de_DE` | `de-de` |\n| English (United Kingdom) | `en_GB` | `en-gb` |\n| English (United States) | `en_US` | `en-us` |\n| Spanish (Spain) | `es_ES` | `es-es` |\n| French (France) | `fr_FR` | `fr-fr` |\n| Indonesian | `id_ID` | `id-id` |\n| Italian | `it_IT` | `it-it` |\n| Japanese | `ja_JP` | `ja-jp` |\n| Korean | `ko_KR` | `ko-kr` |\n| Malay | `ms_MY` | `ms-my` |\n| Polish | `pl_PL` | `pl-pl` |\n| Portuguese (Brazil) | `pt_BR` | `pt-br` |\n| Russian | `ru_RU` | `ru-ru` |\n| Thai | `th_TH` | `th-th` |\n| Turkish | `tr_TR` | `tr-tr` |\n| Vietnamese | `vi_VN` | `vi-vn` |\n| Chinese (Simplified) | `zh_CN` | `zh-cn` |\n| Chinese (Traditional) | `zh_TW` | `zh-tw` |\n\nAny other language logs a warning and only uses `_other` plural keys.\n\n## Migrating from v1\n\n| v1 | v2 |\n| --- | --- |\n| `new Localizer(provider)` | `new Localize({ language, backend })` |\n| `LocalizationProvider` class | `backend = { read = function(language, namespace) ... end }` |\n| `localizer.setLanguage(LanguageCode.en_US)` | `i18n.changeLanguage(\"en_US\")`, which yields |\n| `localizer.getLanguage()` | `i18n.language` |\n| `localizer.languageChangedSignal.Event` | `i18n.LanguageChanged` |\n| `localizer.localize(key, { $count: 1 })` | `i18n.t(key, { count: 1 })` |\n| `{ $ordinal: true }` | `{ ordinal: true }` |\n| `{{$count}}` | `{{count}}` |\n| `apples:one`, `apples:other` | `apples_one`, `apples_other` |\n| `place:ordinal:one` | `place_ordinal_one` |\n| `LanguageCode.en_US` | `\"en_US\"` |\n| `ROBLOX_LANGUAGE_CODE_MAP[localeId]` | `robloxLocaleIdToLanguageCode(localeId)` |\n| `LANGUAGE_CODE_ROBLOX_MAP[code]` | `LanguageMetadata[code].robloxLocaleId` |\n\n\n- **`:` in keys:** this now selects a namespace. If your keys contain it, set\n  `namespaceSeparator` to `false`.\n- **Plural fallback:** without a `count`, `apples` no longer falls back to\n  `apples:other`, so add a plain `apples` key if you need one.\n- **Missing variables:** these stay as `{{name}}` instead of printing `(nil)`.\n- **Removed:**\n  - `getLookupKeyName`\n  - `parseInterpolatable`\n  - `interpolate`\n  - `getKey`\n  - `PLURALIZATION_RULES`\n","readmeTruncated":false}