# @apostrophecms/i18n

Alias: apos.i18n

This module governs internationalization functionality and localization tools. Apostrophe projects will configure locales through @apostrophecms/i18n.

The module makes an instance of the i18next (opens new window) npm module available in Nunjucks templates via the __t() helper function. That function is also available on req objects as req.t() and in user interface Vue.js components as this.$t().

apos.i18n.i18next can be used to directly access the i18next npm module instance if necessary. It usually is not necessary. Use req.t if you need to localize in a route.

# Options

Property Type Description
defaultLocale String The locale that will be used by the UI and server rendering if no other is specified.
locales Object The set of locales to use in the application.

# locales

The locale object should include one or more (usually two or more) locale configuration object. Each locale key is a short code, typically a two letter country code (e.g., ca), language code (fr), or one of each with a dash separating them (fr-CA). This local name is used to reference the locale throughout Apostrophe.

Each locale may have the following settings:

Locale setting Type Description
label String The human-readable label for the locale.
hostname String A hostname (e.g., 'example.net') that will trigger the locale to be shown.
prefix String A URL path prefix that will trigger the locale to be shown.

Hostname and the path prefix are both factors in deciding what locale to display to visitors. There is prioritization that factors into identifying the correct one to use. The priority ranking for choosing the correct locale is:

  1. The locale has both hostname and prefix settings and the URL matches both settings.
  2. The URL matches the locale's configured hostname and the locale has no prefix
  3. The URL matches the locale's configured prefix and the locale has no hostname.
  4. The locale is the default locale (when no other locale matches).

Other notes:

  • Two or more locales may not be registered with the same hostname and the same path prefix. Apostrophe will throw an error in this case.
  • The default locale (either the defaultLocale setting or the first registered locale) does not need a hostname or path prefix setting.
  • If any locale has a hostname setting one of these must be true:
    1. The Apostrophe app must have a baseUrl set in the app.js file (a best practice in most cases anyway), OR
    2. All locales must have a hostname setting (even if several are the same, using different prefix settings).
  • If the URL does not match any locale's set hostname or prefix (and all locales have one or both settings), Apostrophe will use the default locale.

# Project configuration example

module.exports = {
  options: {
    defaultLocale: 'fr',
    locales: {
      fr: {
        label: 'French'
      'en-CA': {
        label: 'Canada (English)',
        prefix: '/ca/en'
      'fr-CA': {
        label: 'Canada (French)',
        prefix: '/ca/fr'
      'es-MX': {
        label: 'Mexico',
        hostname: 'example.mx'

The following locales belong to this module and may be useful in project-level code. See the source code (opens new window) for all methods that belong to this module.

# inferIdLocaleAndMode(req, _id)

Infer req.locale and req.mode from _id if they were not set already by explicit query parameters. Conversely, if the appropriate query parameters were set, rewrite _id accordingly. Returns _id, after rewriting if appropriate.

# isValidLocale(locale)

Given a locale name, this will return a boolean value indicating whether it is a locale configured for the Apostrophe website.

# matchLocale(req)

Return the best matching locale for the request based on the hostname and path prefix. If available the first locale matching both hostname and prefix is returned, otherwise the first matching locale that specifies only a hostname or only a prefix. If no matches are possible the default locale is returned.