Package APIs

@i18n-micro/types

Exported API of @i18n-micro/types, generated from the source.

TypeScript definitions for the Nuxt I18n Micro ecosystem.

import { … } from '@i18n-micro/types'

Functions

init

function init(): void

Types

CleanTranslation

A translation value without the unknown escape hatch.

type CleanTranslation =
  | string
  | number
  | boolean
  | Translations
  | PluralTranslations
  | null

See Translations · PluralTranslations

DefineI18nRouteConfig

Per-page i18n configuration declared via $defineI18nRoute() in page components.

interface DefineI18nRouteConfig
locales
string[] | Record<LocaleCode, Translations>
Restrict which locales this page is available in.
  • string[] — list of allowed locale codes.
  • Record<LocaleCode, Translations> — allowed locales with inline translation overrides.
localeRoutes
Record<LocaleCode, string>
Per-locale custom route paths (e.g. { en: '/about', de: '/ueber-uns' }).
disableMeta
boolean | string[]
Disable SEO meta tag generation for this page.
  • true — disable all meta tags.
  • string[] — disable only for the listed locale codes.

DefineLocaleMessage

Key registry for typed translation keys. Users (via @i18n-micro/types-generator) extend this interface through TypeScript module augmentation to get autocompletion for $t() calls.

interface DefineLocaleMessage
readonly __augmentation
never

Getter

Getter function signature used by pluralization to resolve nested keys.

type Getter = (key: TranslationKey, params?: Record<string, string | number | boolean>, defaultValue?: string) => unknown

See TranslationKey

GlobalLocaleRoutes

Global per-route locale configuration.

  • Record<string, string> — custom paths per locale for the route.
  • false — exclude the route from localization entirely.
  • true — include with default behavior.
type GlobalLocaleRoutes =
  | Record<string, Record<LocaleCode, string> | false | boolean>
  | null
  | undefined

See LocaleCode

I18nBeforeLocaleSwitchContext

The context of the i18n:beforeLocaleSwitch runtime hook. A subscriber may set to (another enabled locale) or cancel: true; an invalid to is ignored.

interface I18nBeforeLocaleSwitchContext
from
string required
The locale shown now.
to
string required
The locale the switch goes to.
cancel
boolean required
true stops the switch: the page and the stored preference stay.

I18nHeadDisableGroup

Groups of built-in i18n SEO tags that can be disabled per page.

type I18nHeadDisableGroup =
  | 'hreflang'
  | 'x-default'
  | 'canonical'
  | 'og'
  | 'og-alternates'
  | 'html'

I18nHeadInput

Page-level overrides merged on top of useLocaleHead output.

interface I18nHeadInput
htmlAttrs
Record<string, string>
Extra or overriding <html> attributes.
meta
I18nHeadMeta[]
Meta tags appended after base i18n tags (deduped by id / property / name).
link
I18nHeadLink[]
Link tags appended after base i18n tags (deduped by id / rel + hreflang).
replace
{ canonical?: string | false; hreflang?: I18nHeadLink[] | false; xDefault?: I18nHeadLink | false; ogLocale?: string | false; ogUrl?: string | false; ogAlternates?: string[] | false; }
Replace or remove specific built-in i18n SEO tags.
disable
I18nHeadDisableGroup[]
Disable built-in i18n SEO tag groups for this page.

I18nHeadLink

Link entry for page-level i18n head overrides (useI18nHead).

interface I18nHeadLink
rel
string required
href
string required
hreflang
string
[key: string]
string | undefined

I18nHeadMeta

Meta entry for page-level i18n head overrides (useI18nHead).

interface I18nHeadMeta
[key: string]
string | undefined

I18nRouteParams

Locale-specific route params for $switchLocalePath and <i18n-link>.

type I18nRouteParams = Record<LocaleCode, Record<string, string>> | null

See LocaleCode

ListParams

A list for {0}, {1}: what t() takes besides Params.

type ListParams = readonly (string | number | boolean)[]

Locale

Locale configuration object.

Supports arbitrary custom properties via the index signature [key: string]: unknown. To get full TypeScript support for your custom properties, use module augmentation:

// app/i18n.d.ts (or any .d.ts file included in your tsconfig)
declare module '@i18n-micro/types' {
  interface Locale {
    flag?: string
    currency?: string
  }
}

Then access them with full typing:

const locales = $getLocales()
locales[0].flag     // string | undefined  (typed!)
locales[0].currency // string | undefined  (typed!)

interface Locale

LocaleCode

BCP-47 locale code string (e.g. 'en', 'de-DE', 'zh-Hans').

type LocaleCode = string

LocaleCookieOptions

Attributes of the locale cookie (localeCookieOptions).

interface LocaleCookieOptions
domain
string
Domain: e.g. .example.com to share the cookie across subdomains. Unset: the host only.
path
string
Default'/' · Path.
secure
boolean
Defaultfalse · Secure: sent over HTTPS only. Required by browsers with sameSite: 'none'.
sameSite
'lax' | 'strict' | 'none'
Default'lax' · SameSite. 'none' (e.g. an app inside an iframe) needs secure: true.
maxAge
number
Default31536000 (one year) · Lifetime in seconds (Max-Age and Expires).

MissingHandler

Callback invoked when a translation key is missing. Useful for logging, reporting, or providing dynamic fallbacks.

type MissingHandler = (locale: string, key: TranslationKey, routeName: string, instance?: unknown, type?: string) => void

See TranslationKey

ModuleOptions

interface ModuleOptions

ModuleOptionsExtend

Extended module options injected into the Nuxt runtime config. Includes resolved values and build-time metadata.

interface ModuleOptionsExtend extends ModuleOptions

See ModuleOptions

ModulePrivateOptionsExtend

Private (server-only) module options passed to Nitro plugins and server middleware. Extends ModuleOptions with resolved root paths and directory info.

interface ModulePrivateOptionsExtend extends ModuleOptions
cacheStorageBuild
string
Nuxt's buildId: cacheStorage keys of two builds never meet.
rootDirs
string[] required
Absolute Nuxt layer roots in merge order (extends first, project last). Used by live/HMR translation reads so layers match build-time merge.
debug
boolean required
Defaultfalse · Resolved debug flag.
translationDir
string required
Default'locales' · Resolved path to the translations directory.
apiBaseServerHost
string
Defaultundefined · Resolved server-side host override.
serverTranslationPreload
boolean
Defaultfalse · Preload index translations in Nitro global middleware.
payloadFsDir
string required
Absolute buildDir path to payload files (.nuxt/i18n-merged or .nuxt/i18n-source). Used by the Node fs reader in import.meta.dev / import.meta.prerender.
payloadPublicRel
string required
Directory under Nitro public/ for prod payload files (defaults to translationDir).

See ModuleOptions

Params

Interpolation parameters passed to the t() function.

type Params = Record<string, string | number | boolean>

PluralFunc

Custom pluralization function. Called when tc() / $tc() is used. Receives the key, count, params, locale, and a getter to fetch the singular/plural forms from translations.

type PluralFunc = (key: TranslationKey, count: number, params: Params, locale: string, getter: Getter) => string | null

See TranslationKey · Params · Getter

PluralTranslations

Object shape for a translation value that contains singular/plural forms.

interface PluralTranslations
singular
string required
Singular form of the translation (count === 1).
plural
string required
Plural form of the translation (count !== 1).

ResolvedI18nConfig

The config the build writes, as getI18nConfig() and $getI18nConfig() give it.

type ResolvedI18nConfig = Omit<ModuleOptionsExtend, ResolvedI18nConfigKey> & Required<Pick<ModuleOptionsExtend, ResolvedI18nConfigKey>>

See ModuleOptionsExtend

RouteI18nMeta

meta.i18n that route-strategy puts on every localized record, and path-strategy reads at runtime.

interface RouteI18nMeta
name
string required
Base route name of the page (its translation key and the name localeRoute({ name }) takes).
locales
string[] required
Locales this record serves.
noMeta
boolean | string[]
disableMeta of the page: SEO tags off in every locale (true) or in the listed ones.
original
string
On the default locale's record: the path of a page with a custom default path, where it is no record of its own. A link can still name the page by it.
paths
Record<string, string>
noPrefixRedirect, on the page's original path: the custom path of each locale. The locale is the visitor's, so the runtime redirects.

ScopedKey

Helper for creating typed prefixes. Allows safe usage of dynamic keys.

type ScopedKey<Scope extends string> = Extract<TranslationKey, `${Scope}.${string}`>

// Assuming keys: 'errors.404', 'errors.500', 'btn.save'
function getErrorText(code: string) {
  return t(`errors.${code}` as ScopedKey<'errors'>)
}

See TranslationKey

Strategies

URL routing strategy for locale handling.

type Strategies =
  | 'no_prefix'
  | 'prefix_except_default'
  | 'prefix'
  | 'prefix_and_default'

TranslateParams

What t() and interpolate take: named params or a list. PluralFunc keeps Params.

type TranslateParams = Params | ListParams

See Params · ListParams

Translation

A single translation value — can be a primitive, nested object, plural pair, or unknown.

type Translation = CleanTranslation | unknown

See CleanTranslation

TranslationKey

Resolved translation key type.

  • When DefineLocaleMessage is empty (generator not connected) — resolves to string.
  • When DefineLocaleMessage has keys — resolves to a union of those keys and(string & {}), providing autocompletion while still allowing dynamic keys (plain | string would collapse the union to string).
type TranslationKey = Exclude<keyof DefineLocaleMessage, '__augmentation'> extends never
  ? string
  : Exclude<keyof DefineLocaleMessage, '__augmentation'> | (string & {})

See DefineLocaleMessage

TranslationPayloadOptions

interface TranslationPayloadOptions

Translations

A flat or nested dictionary of translation key-value pairs.

interface Translations
[key: string]
Translation

Generated from the TypeScript sources and their JSDoc by pnpm run docs:generate. Back to all packages · Integration guides

@i18n-micro/test-utils

Exported API of @i18n-micro/test-utils, generated from the source.

@i18n-micro/types-generator

Exported API of @i18n-micro/types-generator, generated from the source.