I18n

The I18n class is responsible for performing locale-specific formatting. You can get an instance of this class using the I18nManager.locale method.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n.locale('en') // instanceof I18n

Methods/Properties

Following is the list of methods/properties available on the I18n class.

locale

Reference to the locale for which you have created the instance.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n.locale('en').locale === 'en'

fallbackLocale

A read-only reference to the fallbackLocale. Translations from this locale will be used when not available for the main locale.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n.locale('en').fallbackLocale

switchLocale

Switch the locale at runtime. Calling this method will update the locale, and the fallbackLocale.

import I18n from '@ioc:Adonis/Addons/I18n'
const i18n = I18n.locale('en')
// Switch to es
i18n.switchLocale('es')

validatorMessages

Returns an object with a wildcard handler to look up messages for the validator. The method accepts a key prefix from where to fetch the messages.

import I18n from '@ioc:Adonis/Addons/I18n'
const i18n = I18n.locale('en')
I18n.validatorMessages('validator.shared')
I18n.validatorMessages('validator.contact')
I18n.validatorMessages('validator.signup')

hasMessage

Find if the message for a given key has been defined or not.

import I18n from '@ioc:Adonis/Addons/I18n'
const i18n = I18n.locale('en')
if (i18n.hasMessage('messages.greeting')) {
// do something
}

hasFallbackMessage

Find if the fallback message for a given key has been defined or not.

import I18n from '@ioc:Adonis/Addons/I18n'
const i18n = I18n.locale('en')
if (i18n.hasFallbackMessage('messages.greeting')) {
// do something
}

formatMessage

Format a message using the configured formatter (defaults to icu). Make sure to read the in-depth guide on formatting translations .

  • The first argument is the message key to format.
  • The second argument is the runtime data to pass to the message.
import I18n from '@ioc:Adonis/Addons/I18n'
const i18n = I18n.locale('en')
i18n.formatMessage('messages.greeting', { name: 'Virk' })

formatRawMessage

Format a message from a raw string.

  • The first argument is the raw message to format.
  • The second argument is the runtime data to pass to the message.
import I18n from '@ioc:Adonis/Addons/I18n'
const i18n = I18n.locale('en')
i18n.formatRawMessage('Hello {name}', { name: 'Virk' })

formatNumber

The formatNumber uses the Intl.NumberFormat class to format a numeric value.

  • The first argument is the value to format. It must be a number, bigint, or a string representation of a number.

  • The second argument is the options. They are the same as the options accepted by the Intl.NumberFormat class.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n
.locale('en')
.formatNumber(123456.789, {
maximumSignificantDigits: 3
})

formatCurrency

The formatCurrency method uses the Intl.NumberFormat class but implicitly sets the style to currency.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n
.locale('en')
.formatCurrency(200, {
currency: 'USD'
})

formatDate

The formatDate method uses the Intl.DateTimeFormat class to format a date.

  • The first argument is the date to format. It can be an ISO date string, a timestamp, an instance of the JavaScript Date class, or a luxon DateTime.

  • The second argument is the options. They are the same as the options accepted by the Intl.DateTimeFormat class.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n
.locale('en')
.formatDate(new Date(), {
dateStyle: 'long'
})

formatTime

The formatTime method uses the Intl.DateTimeFormat class, but implicitly sets the timeStyle to medium.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n
.locale('en')
.formatTime(new Date(), {
timeStyle: 'long'
})

formatRelativeTime

The formatRelativeTime method using the Intl.RelativeTimeFormat class to format a value to a relative time representation string.

  • The first argument is the value of the relative time. It can be an ISO date string, an absolute numeric diff, an instance of the JavaScript Date class, or an instance of luxon DateTime.

  • The second argument is the formatting unit. Along with the officially supported units , we also support an additional auto unit.

  • The third argument is the options. They are the same as the options accepted by the Intl.RelativeTimeFormat class.

import { DateTime } from 'luxon'
import I18n from '@ioc:Adonis/Addons/I18n'
const luxonDate = DateTime.local().plus({ hours: 2 })
I18n
.locale('en')
.formatRelativeTime(luxonDate, 'hours')

We will find the best unit when using the formatting unit is set to auto. For example:

const luxonDate = DateTime.local().plus({ hours: 2 })
I18n
.locale('en')
.formatRelativeTime(luxonDate, 'auto')
// In 2 hours 👈
const luxonDate = DateTime.local().plus({ hours: 200 })
I18n
.locale('en')
.formatRelativeTime(luxonDate, 'auto')
// In 8 days 👈

formatPlural

The formatPlural method uses the Intl.PluralRules and returns a plural category for a given numeric value.

  • The first argument is the value. It must be a number or a string representation of a number.

  • The second argument is the options. They are the same as the options accepted by the Intl.PluralRules class.

import I18n from '@ioc:Adonis/Addons/I18n'
I18n.locale('en').formatPlural(0)
// other
I18n.locale('en').formatPlural(1)
// one
I18n.locale('en').formatPlural(2)
// other