Internationalization

Every user-visible string in the host-kit screens (and the flash / error messages the controllers produce) lives in a flat catalog of dotted keys. The built-in default is English (en), so apps work with no configuration. pt-BR ships as a built-in locale: flip it on with i18n: { locale: 'pt-BR' }. You can also override individual keys or provide whole new locales via i18n.

The default catalog

DEFAULT_MESSAGES (exported) is the English catalog — it covers every screen: login.*, signup.*, forgot.*, reset.*, verify_email.*, mfa_challenge.*, consent.*, account.*, admin.*, device.*, the transactional mail.* strings, plus the controller errors under errors.*. DEFAULT_LOCALE is 'en'.

PT_BR_MESSAGES (also exported) is the built-in pt-BR catalog — it mirrors every key. The two built-in catalogs are registered in BUILTIN_MESSAGES ({ en, 'pt-BR' }).

Built-in pt-BR (zero config)

To run the screens in pt-BR, just set the locale — you do not need to provide any messages:

import { defineConfig } from '@adonis-agora/authkit-server'

export default defineConfig({
  // ...
  i18n: { locale: 'pt-BR' },
})

Overriding keys / adding locales

import { defineConfig } from '@adonis-agora/authkit-server'
import type { I18nConfig } from '@adonis-agora/authkit-server'

const i18n: I18nConfig = {
  locale: 'en',
  messages: {
    // Override individual keys of the active (default) locale.
    en: {
      'login.title': 'Sign in',
      'errors.invalid_credentials': 'Those credentials did not match.',
      // omitted keys fall back to the English default
    },
    // Or ship a whole new locale.
    fr: {
      'login.title': 'Connexion',
      'login.submit': 'Se connecter',
      // omitted keys fall back to the English default
    },
  },
}

export default defineConfig({
  // ...
  i18n,
})

You can also override a few keys on top of the built-in pt-BR catalog:

const i18n: I18nConfig = {
  locale: 'pt-BR',
  messages: {
    'pt-BR': { 'login.title': 'Acessar' }, // rest stays pt-BR
  },
}

How resolution works

resolveMessages(i18n) starts from the active locale's built-in catalog (or the English default when the locale is not built in), then merges the host's overrides on top. Keys the chosen locale omits fall back to English (so partial locales still render fully). The resolved catalog is exposed on the server config as messages (and locale), ready for the renderers and the transactional mailer.

import {
  resolveMessages,
  translate,
  DEFAULT_MESSAGES,
  PT_BR_MESSAGES,
} from '@adonis-agora/authkit-server'

resolveMessages() // English defaults
resolveMessages({ locale: 'pt-BR' }) // built-in pt-BR, no messages needed

const messages = resolveMessages({ locale: 'en', messages: { en: { 'login.title': 'Sign in' } } })
translate(messages, 'login.greeting', { name: 'Ada' }) // "Hi, Ada"

translate(messages, key, params?) returns the string for key (falling back to the key itself when missing) and interpolates {name}-style placeholders — leaving unmatched placeholders intact.