{"id":11066,"library":"i18n-ts","title":"Type-Safe Internationalization for TypeScript","description":"i18n-ts is a lightweight, type-safe internationalization library designed specifically for TypeScript applications. It allows developers to define translation messages as plain TypeScript objects, leveraging TypeScript's robust type inference system to ensure that message keys and their associated arguments are correctly used at compile time. This approach significantly reduces runtime errors related to missing translations or incorrect parameter usage, a common issue in dynamic i18n systems. The current stable version is 1.0.5, suggesting a relatively mature and stable codebase with a likely slow release cadence. Its key differentiator lies in its deep integration with TypeScript, providing compile-time safety without requiring external build steps or complex configuration files often found in other i18n solutions. It focuses on simplicity and type inference over a feature-rich runtime, making it ideal for projects prioritizing strong typing in their i18n layer.","status":"active","version":"1.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/sparkbitpl/i18n-ts","tags":["javascript","i18n","TypeScript","internationalization","typescript"],"install":[{"cmd":"npm install i18n-ts","lang":"bash","label":"npm"},{"cmd":"yarn add i18n-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add i18n-ts","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class for resolving translations; typically used with named import.","wrong":"const I18nResolver = require('i18n-ts');","symbol":"I18nResolver","correct":"import { I18nResolver } from 'i18n-ts';"}],"quickstart":{"code":"import { I18nResolver } from 'i18n-ts';\n\nconst en = {\n    hello: \"Hi!\",\n    greeting: (name: string) => `Hi ${name}`\n};\n\nconst de = {\n    hello: \"Hallo!\",\n    greeting: (name: string) => `Hallo ${name}`\n};\n\nconst i18n = {\n    en: en,\n    de: de,\n    default: en\n};\n\n// Initialize the resolver with your locales and desired language\nconst messages = new I18nResolver(i18n, \"de\").translation;\n\n// TypeScript will infer the precise type of 'messages', providing compile-time safety\nconsole.log(messages.hello); // Output: Hallo!\nconsole.log(messages.greeting(\"Alice\")); // Output: Hallo Alice\n\n// Example of changing the language\nconst messagesEn = new I18nResolver(i18n, \"en\").translation;\nconsole.log(messagesEn.hello); // Output: Hi!\n","lang":"typescript","description":"Demonstrates defining type-safe translation messages as plain TypeScript objects and using I18nResolver to access them."},"warnings":[{"fix":"For complex pluralization or formatting, manually add logic within your message functions, e.g., `(count: number) => count === 1 ? 'item' : 'items'`.","message":"i18n-ts does not provide built-in support for complex i18n features like pluralization, gender, or sophisticated ICU MessageFormat. Users must implement these functionalities manually within their message functions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider code-splitting translation files if bundle size is a concern, and implement manual loading logic to pass the correct locale object to I18nResolver at runtime.","message":"All translation messages defined as plain TypeScript objects are typically bundled with your application by default. This can lead to increased bundle sizes for applications supporting a large number of locales, as there is no built-in dynamic locale loading mechanism.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always review the release notes carefully when upgrading to a new major version. Test your translation files thoroughly after any major version upgrade.","message":"Major version updates (e.g., v2.0.0) could introduce breaking changes to the expected structure of locale objects or the way message functions receive arguments, necessitating updates to your existing translation files.","severity":"breaking","affected_versions":"unknown"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the translation key exists in the active locale object and matches the exact property name. TypeScript's inference will highlight these issues at compile time.","cause":"Attempting to access a translation key that is not defined in the loaded locale object or has a typo.","error":"TS2339: Property 'nonExistentKey' does not exist on type '{ hello: string; greeting: (name: string) => string; }'."},{"fix":"Pass arguments to your translation functions that precisely match the type signatures defined in your locale objects. TypeScript provides strong type checking for this.","cause":"Providing an argument of the wrong type to a translation function, as defined in your locale object (e.g., calling `greeting(123)` when `greeting` expects a `string`).","error":"TS2345: Argument of type 'number' is not assignable to parameter of type 'string'."},{"fix":"Verify that the `i18n` object is correctly structured with defined locale objects (e.g., `en`, `de`) and that the selected locale key matches one of the defined keys. Also, ensure a `default` locale is provided.","cause":"The `i18n` object passed to `I18nResolver` is malformed, the selected locale key (e.g., 'de') does not exist within it, or `default` locale is missing.","error":"TypeError: Cannot read properties of undefined (reading 'translation')"}],"ecosystem":"npm"}