{"id":11090,"library":"international-types","title":"International Types","description":"international-types is a focused TypeScript package that provides essential utility types for constructing robust and type-safe internationalization (i18n) solutions. It is designed to enhance developer experience by offering strong type inference and autocompletion for translation keys, message scopes, and interpolation parameters within i18n implementations. The current stable version is 0.8.1. While this package does not provide any runtime i18n functionality itself, it serves as the foundational typing layer for higher-level i18n libraries, such as `next-international`. Its core differentiators are compile-time validation, preventing common i18n-related errors like missing keys or incorrect parameter types, and promoting maintainability in localized applications by ensuring all translation requirements are met at build time. Its release cycle is often synchronized with its primary consumer, `next-international`.","status":"active","version":"0.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/QuiiBz/next-international","tags":["javascript","i18n","types","typescript","translate","internationalization"],"install":[{"cmd":"npm install international-types","lang":"bash","label":"npm"},{"cmd":"yarn add international-types","lang":"bash","label":"yarn"},{"cmd":"pnpm add international-types","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Always use 'import type' for type-only imports to avoid accidental runtime imports and ensure type safety.","wrong":"import { LocaleKeys } from 'international-types'","symbol":"LocaleKeys","correct":"import type { LocaleKeys } from 'international-types'"},{"note":"Used to infer nested translation scopes based on your locale object structure.","wrong":"import { Scopes } from 'international-types'","symbol":"Scopes","correct":"import type { Scopes } from 'international-types'"},{"note":"Essential for defining the expected types of translation parameters, enabling autocompletion and validation.","wrong":"import { CreateParams } from 'international-types'","symbol":"CreateParams","correct":"import type { CreateParams } from 'international-types'"},{"note":"The base interface for your entire locale object, providing a consistent structure for type inference.","wrong":"import { BaseLocale } from 'international-types'","symbol":"BaseLocale","correct":"import type { BaseLocale } from 'international-types'"}],"quickstart":{"code":"import type {\n  LocaleKeys,\n  BaseLocale,\n  Scopes,\n  ScopedValue,\n  CreateParams,\n  ParamsObject\n} from 'international-types';\n\ntype AppLocale = {\n  param: 'This is a {value}';\n  'hello.people': 'Hello {name}! You are {age} years old.';\n  'scope.nested.greeting': 'A nested greeting.';\n};\n\nfunction createI18nTypedT<Locale extends BaseLocale, Scope extends Scopes<Locale> | undefined>(scope?: Scope) {\n  return function t<Key extends LocaleKeys<Locale, Scope>, Value extends ScopedValue<Locale, Scope, Key>>(\n    key: Key,\n    ...params: CreateParams<ParamsObject<Value>, Locale, Scope, Key, Value>\n  ) {\n    // In a real i18n library, this function would handle the actual translation lookup and interpolation.\n    // For this example, we just log the key and params to demonstrate type safety.\n    console.log(`Translating key: ${String(key)} with params: ${JSON.stringify(params[0]) || '{}'}`);\n\n    // Example: Dummy return for a type-safe signature\n    return `Translated: ${String(key)}`\n  };\n}\n\nconst t = createI18nTypedT<AppLocale, undefined>();\n\nt('param', {\n  value: 'exampleValue' // 'value' is required and type-checked here\n});\n\nt('hello.people', {\n  name: 'John Doe',\n  age: 30 // 'name' and 'age' are required and type-checked\n});\n\nconst scopedT = createI18nTypedT<AppLocale, 'scope.nested'>('scope.nested');\n\nscopedT('greeting'); // Autocompletes to 'greeting' under 'scope.nested'\n\n// Example of intentionally incorrect usage (will cause TypeScript errors)\n// t('non.existent.key');\n// t('param', { wrongParam: 'value' });\n// t('hello.people', { name: 'Alice' }); // Missing 'age' parameter\n","lang":"typescript","description":"This quickstart demonstrates how to set up type-safe translation keys, scopes, and parameters using `international-types`. It shows how to define a locale type, create a `t` function with robust type inference, and ensures that translation keys exist and all required interpolation parameters are provided at compile time, reducing runtime errors."},"warnings":[{"fix":"Pair `international-types` with a full-fledged i18n runtime library to handle translation string loading, interpolation, and locale management.","message":"This package (`international-types`) provides only TypeScript types and does not include any runtime internationalization logic or components. It must be integrated with a separate i18n library (like `next-international` or a custom implementation) to provide actual translation capabilities.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Carefully review the `Locale` type definition to ensure it accurately reflects your translation structure, matching string literals for keys and values, and using dot notation for nested keys if desired.","message":"Incorrectly defining your `Locale` type (e.g., not matching the expected flat or dot-notation structure) will lead to incorrect or incomplete type inference for `LocaleKeys` and `Scopes`. This can result in a loss of type safety and autocompletion benefits.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"While generally performant, consider flattening extremely deep locale structures if compile times become an issue, or ensure your TypeScript configuration is optimized (e.g., using project references, incremental builds).","message":"The package relies heavily on TypeScript's inference capabilities. In very large projects with extremely complex or deeply nested locale structures, TypeScript compilation times might be slightly affected. Type-checking performance can degrade with overly intricate generic types.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure translation keys are always string literals for direct calls. If dynamic keys are necessary, you might need a runtime lookup combined with type assertion (e.g., `t(dynamicKey as LocaleKeys<AppLocale, undefined>)`) or rethink the approach, acknowledging a loss of compile-time key validation for that specific call.","cause":"Attempting to pass a dynamic string variable as a translation key instead of a literal string. The types require literal keys for compile-time validation.","error":"Argument of type 'string' is not assignable to parameter of type 'Key extends LocaleKeys<AppLocale, undefined>'"},{"fix":"Provide all necessary parameters as defined in your `Locale` type for the specific translation key. Double-check the parameter names and their types.","cause":"A required interpolation parameter for a translation string was omitted or incorrectly named when calling the translation function.","error":"Property 'value' is missing in type '{}' but required in type '{ value: string; }'"},{"fix":"Run `npm install international-types` or `pnpm install international-types`. Ensure `tsconfig.json` includes `node_modules` in its `typeRoots` or `include` paths, or that `moduleResolution` is set appropriately for your project (e.g., `bundler` or `node`).","cause":"The package is not installed, or TypeScript cannot locate its declaration files (e.g., incorrect `tsconfig.json` paths, or `node_modules` not properly resolved).","error":"TS2307: Cannot find module 'international-types' or its corresponding type declarations."}],"ecosystem":"npm"}