Registry / type-stubs / international-types

international-types

JSON →
library0.8.1jsnpmunverified

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`.

npm install international-types
INSTALL
IMPORT
SIG · INTERNATIONAL-TYPE
I
international-types
type-stubsjavascriptv0.8.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LocaleKeys
import type { LocaleKeys } from 'international-types'
import { LocaleKeys } from 'international-types'
Always use 'import type' for type-only imports to avoid accidental runtime imports and ensure type safety.
Scopes
import type { Scopes } from 'international-types'
import { Scopes } from 'international-types'
Used to infer nested translation scopes based on your locale object structure.
CreateParams
import type { CreateParams } from 'international-types'
import { CreateParams } from 'international-types'
Essential for defining the expected types of translation parameters, enabling autocompletion and validation.
BaseLocale
import type { BaseLocale } from 'international-types'
import { BaseLocale } from 'international-types'
The base interface for your entire locale object, providing a consistent structure for type inference.

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.

import type { LocaleKeys, BaseLocale, Scopes, ScopedValue, CreateParams, ParamsObject } from 'international-types'; type AppLocale = { param: 'This is a {value}'; 'hello.people': 'Hello {name}! You are {age} years old.'; 'scope.nested.greeting': 'A nested greeting.'; }; function createI18nTypedT<Locale extends BaseLocale, Scope extends Scopes<Locale> | undefined>(scope?: Scope) { return function t<Key extends LocaleKeys<Locale, Scope>, Value extends ScopedValue<Locale, Scope, Key>>( key: Key, ...params: CreateParams<ParamsObject<Value>, Locale, Scope, Key, Value> ) { // In a real i18n library, this function would handle the actual translation lookup and interpolation. // For this example, we just log the key and params to demonstrate type safety. console.log(`Translating key: ${String(key)} with params: ${JSON.stringify(params[0]) || '{}'}`); // Example: Dummy return for a type-safe signature return `Translated: ${String(key)}` }; } const t = createI18nTypedT<AppLocale, undefined>(); t('param', { value: 'exampleValue' // 'value' is required and type-checked here }); t('hello.people', { name: 'John Doe', age: 30 // 'name' and 'age' are required and type-checked }); const scopedT = createI18nTypedT<AppLocale, 'scope.nested'>('scope.nested'); scopedT('greeting'); // Autocompletes to 'greeting' under 'scope.nested' // Example of intentionally incorrect usage (will cause TypeScript errors) // t('non.existent.key'); // t('param', { wrongParam: 'value' }); // t('hello.people', { name: 'Alice' }); // Missing 'age' parameter
Debug
Known issues
gotchaThis 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.
fix
Pair `international-types` with a full-fledged i18n runtime library to handle translation string loading, interpolation, and locale management.
affects: >=0.1.0
gotchaIncorrectly 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.
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.
affects: >=0.1.0
gotchaThe 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.
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).
affects: >=0.1.0
Errors
Common errors & fixes
Argument of type 'string' is not assignable to parameter of type 'Key extends LocaleKeys<AppLocale, undefined>'
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.
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.
Property 'value' is missing in type '{}' but required in type '{ value: string; }'
A required interpolation parameter for a translation string was omitted or incorrectly named when calling the translation function.
fix
Provide all necessary parameters as defined in your `Locale` type for the specific translation key. Double-check the parameter names and their types.
TS2307: Cannot find module 'international-types' or its corresponding type declarations.
The package is not installed, or TypeScript cannot locate its declaration files (e.g., incorrect `tsconfig.json` paths, or `node_modules` not properly resolved).
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`).
Upgrade
Version history
0.8.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
41 hits · last 30 days
node
36
OpenAI (training)
1
Resources
international-types — npm install international-types · libregistry