International Types

Common errors

• Argument of type 'string' is not assignable to parameter of type 'Key extends LocaleKeys<AppLocale, undefined>'

  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.
  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; }'

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

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

Warnings

• gotcha 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.
  Fix: Pair `international-types` with a full-fledged i18n runtime library to handle translation string loading, interpolation, and locale management.
• gotcha 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.
  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.
• gotcha 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.
  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).

Install

• npm install international-types npm
• yarn add international-types yarn
• pnpm add international-types pnpm

Imports

• LocaleKeys
  wrong:

  import { LocaleKeys } from 'international-types'

  correct:

  import type { LocaleKeys } from 'international-types'

  Always use 'import type' for type-only imports to avoid accidental runtime imports and ensure type safety.
• Scopes
  wrong:

  import { Scopes } from 'international-types'

  correct:

  import type { Scopes } from 'international-types'

  Used to infer nested translation scopes based on your locale object structure.
• CreateParams
  wrong:

  import { CreateParams } from 'international-types'

  correct:

  import type { CreateParams } from 'international-types'

  Essential for defining the expected types of translation parameters, enabling autocompletion and validation.
• BaseLocale
  wrong:

  import { BaseLocale } from 'international-types'

  correct:

  import type { BaseLocale } from 'international-types'

  The base interface for your entire locale object, providing a consistent structure for type inference.

Quickstart

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