Runtime API

Runtime imports come from @number10/typekit-i18n.

Core Types

• TranslationTable<TKey, TLanguage>
• Placeholder and PlaceholderValue
• MissingTranslationEvent
• PlaceholderFormatterMap

createTranslator(table, options?)

Creates a typed translator function:

;(key, language?, placeholder?) => string

Options:

• defaultLanguage?: TLanguage ('en' by default when available in table)
• language?: TLanguage (initial active language, defaults to defaultLanguage)
• missingStrategy?: 'fallback' | 'strict'
• formatters?: PlaceholderFormatterMap<TKey, TLanguage>
• onMissingTranslation?: (event) => void

Missing reasons:

• missingKey
• missingLanguage
• missingFallback

Behavior summary:

• uses target language value when non-empty
• falls back to defaultLanguage when target language value is empty
• defaultLanguage falls back to 'en' when omitted and available in table
• creating a translator throws when defaultLanguage is omitted and table does not contain 'en'
• returns key when no value can be resolved
• throws in strict mode

Category-aware APIs:

• translateIn(category, key, language?, placeholder?)
• in(category, key, language?, placeholder?) (alias of translateIn)
• withCategory(category) (returns a category-bound translate function)

Language state APIs:

• setLanguage(language)
• getLanguage()

Example:

import { createTranslator } from '@number10/typekit-i18n'
import { translationTable } from './generated/translationTable'

const t = createTranslator(translationTable)

t('welcome_title') // active language ("en" by default)
t.setLanguage('de')
t('welcome_title') // now "de"

t.in('home', 'welcome_title')

const tHome = t.withCategory('home')
tHome('welcome_title')

createIcuTranslator(table, options?)

Same base behavior as createTranslator, plus ICU rendering.

Additional option:

• localeByLanguage?: Partial<Record<TLanguage, string>>

Supported ICU subset:

• select: {gender, select, male {...} female {...} other {...}}
• plural: {count, plural, =0 {...} one {...} other {...}}
• plural with offset: {count, plural, offset:1 one {...} other {...}}
• selectordinal: {place, selectordinal, one {...} two {...} few {...} other {...}}
• number arguments:
  • {amount, number}
  • {ratio, number, percent}
  • {amount, number, currency/EUR}
  • skeleton form: {amount, number, ::compact-short}
• date/time arguments:
  • {when, date, short|medium|long|full}
  • {when, time, short|medium|long|full}
  • skeleton form: {when, time, ::HH:mm} or {when, date, ::yyyy-MM-dd}
• # replacement in plural/selectordinal branches
• apostrophe escaping ('', quoted literals)

Explicitly unsupported ICU features:

• expression types outside the supported subset, for example choice
• select numeric selectors like =1 (numeric selectors are only supported in plural/selectordinal)
• full ICU number skeleton support (only documented tokens are supported)
• full ICU date/time skeleton support (only documented pattern letters are supported)
• MessageFormat-2 syntax

Invalid ICU expressions throw detailed syntax errors with key, language, line, and column.

createFormatjsIcuTranslator(table, options?)

Runtime import:

import { createFormatjsIcuTranslator } from '@number10/typekit-i18n/runtime/icu-formatjs'

Behavior:

• same translator API shape as createIcuTranslator
• ICU rendering delegated to intl-messageformat (FormatJS)
• supports legacy {name|formatter} placeholders for backward compatibility
• intl-messageformat is an optional peer dependency and only needed for this import path

Placeholder Replacement

Payload shape:

{
  data: [{ key: 'name', value: 'Mara' }]
}

Tokens:

• {name}: raw replacement
• {amount|currency}: named formatter callback

If formatter is missing, fallback is String(value).

Translation Runtime Object

createTranslationRuntime(table, options?) returns:

• translate(key, language?, placeholder?)
• translateIn(category, key, language?, placeholder?)
• withCategory(category)
• setLanguage(language)
• getLanguage()
• configure(options)
• getCollectedMissingTranslations()
• clearCollectedMissingTranslations()

configure can update:

• defaultLanguage
• language
• missingStrategy
• onMissingTranslation (null clears)
• formatters (null clears)
• collectMissingTranslations

Default Runtime Helpers

Also exported:

• translate(...)
• translateIn(...)
• withCategory(...)
• configureTranslationRuntime(...)
• setLanguage(...)
• getLanguage()
• getCollectedMissingTranslations()
• clearCollectedMissingTranslations()
• createConsoleMissingTranslationReporter(writer?)