API reference

All exports are available from the main package entry point.

import { t, tr, withLocale, createCommandConfig, loadLocales, clearFormatterCache } from '@robojs/i18n'
import type { Locale, LocaleKey, ParamsFor, LocaleLike, PluginConfig } from '@robojs/i18n'

import { t, tr, withLocale, createCommandConfig, loadLocales, clearFormatterCache } from '@robojs/i18n'

Functions

`t()`

Formats a localized message by key. Parameters are optional and their types are inferred from the MF2 message syntax.

function t<K extends LocaleKey>(
	locale: LocaleLike,
	key: K,
	params?: ParamsFor<K>
): ReturnOf<K>

function t(
	locale: LocaleLike,
	key: K,
	params?: ParamsFor<K>
): ReturnOf<K>

Prop

Type

Returns string for scalar keys, string[] for array keys.

t('en-US', 'app:hello', { name: 'Robo' })           // "Hello Robo!"
t('en-US', 'app:pets.count', { count: 3 })           // "You have 3 pets"
t(interaction, 'app:hello', { name: 'Robo' })        // uses interaction.locale

t('en-US', 'app:hello', { name: 'Robo' })           // "Hello Robo!"
t('en-US', 'app:pets.count', { count: 3 })           // "You have 3 pets"
t(interaction, 'app:hello', { name: 'Robo' })        // uses interaction.locale

Throws if locales aren't loaded, the locale doesn't exist, or the key is missing. See error reference for details.

`tr()`

Strict variant of t(). When a key has parameters, all are required and non-undefined.

function tr<K extends LocaleKey>(
	locale: LocaleLike,
	key: K,
	...args: MaybeArgs<K>
): ReturnOf<K>

function tr(
	locale: LocaleLike,
	key: K,
	...args: MaybeArgs<K>
): ReturnOf<K>

Prop

Type

tr('en-US', 'app:hello', { name: 'Robo' })  // OK
// tr('en-US', 'app:hello')                  // compile error
tr('en-US', 'app:ping')                      // OK — no params needed

tr('en-US', 'app:hello', { name: 'Robo' })  // OK
// tr('en-US', 'app:hello')                  // compile error
tr('en-US', 'app:ping')                      // OK — no params needed

`withLocale()`

Creates a curried translator bound to a specific locale. Supports loose and strict modes.

// Loose mode (default)
function withLocale(locale: LocaleLike): <K extends LocaleKey>(
	key: K,
	params?: ParamsFor<K>
) => ReturnOf<K>

// Strict mode
function withLocale(locale: LocaleLike, opts: { strict: true }): <K extends LocaleKey>(
	key: K,
	...args: MaybeArgs<K>
) => ReturnOf<K>

// Loose mode (default)
function withLocale(locale): <K extends LocaleKey>(
	key: K,
	params?: ParamsFor<K>
) => ReturnOf<K>

// Strict mode
function withLocale(locale, opts): <K extends LocaleKey>(
	key: K,
	...args: MaybeArgs<K>
) => ReturnOf<K>

Prop

Type

const t$ = withLocale(interaction)
t$('app:hello', { name: 'Robo' })

const tr$ = withLocale('en-US', { strict: true })
tr$('app:hello', { name: 'Robo' })  // params required

const t$ = withLocale(interaction)
t$('app:hello', { name: 'Robo' })

const tr$ = withLocale('en-US', { strict: true })
tr$('app:hello', { name: 'Robo' })  // params required

`createCommandConfig()`

Creates a localized Robo.js command configuration. Drop-in replacement for the robo.js version with i18n key support.

function createCommandConfig<const C extends LocaleCommandConfig>(
	config: ValidatedCommandConfig<C>
): SmartCommandConfig<BaseFromLocale<C>>

function createCommandConfig(
	config: ValidatedCommandConfig<C>
): SmartCommandConfig<BaseFromLocale<C>>

Prop

Type

See Discord commands for usage details and examples.

`loadLocales()`

Scans /locales/**/*.json, builds namespaced keys, stores data in Robo.js State, and generates TypeScript types. Returns elapsed time in milliseconds.

function loadLocales(): number

function loadLocales(): number

This runs automatically via the start lifecycle hook (src/robo/start.ts). Call it manually for testing or non-Robo environments.

import { loadLocales } from '@robojs/i18n'

const ms = loadLocales()
console.log(`Loaded in ${ms}ms`)

import { loadLocales } from '@robojs/i18n'

const ms = loadLocales()
console.log(`Loaded in ${ms}ms`)

`clearFormatterCache()`

Clears the in-memory cache of compiled MessageFormat instances.

function clearFormatterCache(): void

function clearFormatterCache(): void

import { clearFormatterCache } from '@robojs/i18n'

// In test setup
beforeEach(() => {
	clearFormatterCache()
})

import { clearFormatterCache } from '@robojs/i18n'

// In test setup
beforeEach(() => {
	clearFormatterCache()
})

Types

`Locale`

Union of all discovered locale strings. Generated from /locales directory names.

type Locale = 'en-US' | 'es-ES' | ...

`LocaleKey`

Union of all namespaced translation keys. Generated from locale file paths and JSON structure.

type LocaleKey = 'app:hello' | 'app:pets.count' | 'shared/common:greet' | ...

`ParamsFor<K>`

Maps a LocaleKey to its parameter type object. All fields are optional.

type ParamsFor<K extends LocaleKey> = LocaleParamsMap[K]

// Example resolved types:
ParamsFor<'app:hello'>        // { name?: string }
ParamsFor<'app:pets.count'>   // { count?: number }
ParamsFor<'app:event'>        // { ts?: Date | number }
ParamsFor<'app:profile'>      // { user?: { name?: string }, stats?: { count?: number } }


// Example resolved types:
ParamsFor<'app:hello'>        // { name?: string }
ParamsFor<'app:pets.count'>   // { count?: number }
ParamsFor<'app:event'>        // { ts?: Date | number }
ParamsFor<'app:profile'>      // { user?: { name?: string }, stats?: { count?: number } }

`ReturnOf<K>`

Resolves to string for scalar keys, string[] for array keys.

type ReturnOf<K extends LocaleKey> = LocaleIsArrayMap[K] extends true ? string[] : string

`LocaleLike`

Accepted locale inputs for t(), tr(), and withLocale().

type LocaleLike =
	| Locale
	| { locale: string }
	| { guildLocale: string }

	| Locale
	| { locale: string }
	| { guildLocale: string }

Accepts raw locale strings, objects with a locale property (like Discord Interactions), or objects with a guildLocale property.

`PluginConfig`

Plugin configuration interface.

interface PluginConfig {
	defaultLocale?: string  // default: 'en-US'
}

`StrictParamsFor<K>`

Deep-required version of ParamsFor<K>. All fields become required and non-nullable, recursively. Used internally by tr().

type StrictParamsFor<K extends LocaleKey> = DeepRequired<ParamsFor<K>>

// Example:
StrictParamsFor<'app:hello'>   // { name: string }
StrictParamsFor<'app:profile'> // { user: { name: string }, stats: { count: number } }


// Example:
StrictParamsFor<'app:hello'>   // { name: string }
StrictParamsFor<'app:profile'> // { user: { name: string }, stats: { count: number } }

`MaybeArgs<K>`

Conditional tuple type used by tr(). Resolves to [StrictParamsFor<K>] when the key has parameters, or [] when it doesn't.

type MaybeArgs<K extends LocaleKey> = keyof ParamsFor<K> extends never
	? []
	: [StrictParamsFor<K>]

	? []
	: [StrictParamsFor<K>]

Next Steps

Quick start

Set up locale files and start translating.

Discord commands

Localize slash command names and descriptions.

Configuration

Plugin options, MF2 syntax, and type generation.

API reference

Quick start

Discord commands

Configuration

On this page