Types Reference

All TypeScript types exported by the library.

Core Types

I18n

The main i18n instance interface with all translation and management methods.

interface I18n {
  t: TranslateFunction
  getLocale: () => string
  setLocale: (locale: string) => I18n
  setLocaleAsync: (locale: string) => Promise<I18n>
  getAvailableLocales: () => string[]
  addTranslations: (locale: string, translations: TranslationObject) => I18n
  hasKey: (key: string, locale?: string) => boolean
  getTranslations: (locale?: string) => TranslationObject
  loadLocale: (locale: string, options?: LoadLocaleOptions) => Promise<void>
  isLocaleLoaded: (locale: string) => boolean
  onChange: (callback: ChangeCallback) => () => void
  onMissing: (callback: MissingCallback) => () => void
  setMissingBehavior: (behavior: MissingBehavior) => I18n
  namespace: (prefix: string | null | undefined) => TranslateFunction
  formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string
  formatDate: (value: Date | number | string, options?: Intl.DateTimeFormatOptions) => string
  formatRelativeTime: (value: number, unit: Intl.RelativeTimeFormatUnit) => string
}

I18nOptions

Configuration options for createI18n().

interface I18nOptions {
  defaultLocale: string
  fallbackLocale?: string
  translations?: Record<string, TranslationObject>
  loadPath?: LoadPathFunction
}

Example:

const options: I18nOptions = {
  defaultLocale: 'en',
  fallbackLocale: 'en',
  translations: {
    en: { greeting: 'Hello' },
    es: { greeting: 'Hola' }
  },
  loadPath: async (locale) => {
    const res = await fetch(`/locales/${locale}.json`)
    return res.json()
  }
}

TranslateFunction

The t() function type with the namespace method.

interface TranslateFunction {
  (key: string, params?: InterpolationParams): string
  namespace: (prefix: string | null | undefined) => TranslateFunction
}

Example:

const t: TranslateFunction = i18n.t

t('greeting')                    // Call as function
t('greeting', { name: 'World' }) // With params
t.namespace('common')            // Create namespaced function

Translation Types

TranslationObject

A nested object containing translation values.

interface TranslationObject {
  [key: string]: TranslationValue
}

Example:

const translations: TranslationObject = {
  greeting: 'Hello',
  nested: {
    key: 'Nested value'
  },
  items: {
    one: '{{count}} item',
    other: '{{count}} items'
  }
}

TranslationValue

A union type for all possible translation values.

type TranslationValue = string | TranslationObject | PluralTranslations

PluralTranslations

Object containing plural forms for a translation.

interface PluralTranslations {
  zero?: string
  one?: string
  two?: string
  few?: string
  many?: string
  other: string
}

Example:

const plurals: PluralTranslations = {
  zero: 'No items',
  one: '{{count}} item',
  other: '{{count}} items'
}

InterpolationParams

Parameters for interpolation in translations.

type InterpolationParams = Record<string, string | number | boolean | null | undefined>

Example:

const params: InterpolationParams = {
  name: 'Alice',
  count: 5,
  active: true,
  optional: null
}

Callback Types

ChangeCallback

Callback function for locale change events.

type ChangeCallback = (newLocale: string, prevLocale: string) => void

Example:

const callback: ChangeCallback = (newLocale, prevLocale) => {
  console.log(`Changed from ${prevLocale} to ${newLocale}`)
}

MissingCallback

Callback function for missing translation events.

type MissingCallback = (key: string, locale: string) => void

Example:

const callback: MissingCallback = (key, locale) => {
  console.warn(`Missing: ${key} in ${locale}`)
}

Configuration Types

MissingBehavior

Behavior mode when a translation is missing.

type MissingBehavior = 'key' | 'empty' | 'throw'

LoadPathFunction

Async function type for loading translations dynamically.

type LoadPathFunction = (locale: string) => Promise<TranslationObject>

Example:

const loadPath: LoadPathFunction = async (locale) => {
  const response = await fetch(`/locales/${locale}.json`)
  if (!response.ok) throw new Error(`Failed to load ${locale}`)
  return response.json()
}

LoadLocaleOptions

Options for loadLocale().

interface LoadLocaleOptions {
  forceReload?: boolean
}

Error Types

I18nError

Error thrown for i18n-specific errors (e.g., missing translations in throw mode).

class I18nError extends Error {
  name: 'I18nError'
}

Example:

import { I18nError } from '@motioneffector/i18n'

try {
  i18n.setMissingBehavior('throw')
  i18n.t('missing.key')
} catch (error) {
  if (error instanceof I18nError) {
    console.error('Translation error:', error.message)
  }
}