Lazy-load translations

How to lazy-load translations.

For apps that contain a lot of translated content, it is preferable not to bundle all the messages in the main bundle but rather lazy-load only the language that the users selected. This can be achieved with Nuxt i18n module by letting the module know where your translation files are located so it can dynamically import them when the app loads or when the user switches to another language. To enable translations lazy-loading, follow these steps when configuring Nuxt i18n module:

• Set lazy option to true (or to configuration object if you want to customize some options).
• Set langDir option to the directory (can not be empty) that contains your translation files.
• Configure locales option as an array of object, where each object has a file or files key whose value is the translation file corresponding to the locale.
• Optionally, remove all messages that you might have passed to Vue I18n via vueI18n option.
• Each file can return either an Object.

Basic usage

Example files structure:

nuxt-project/
├── lang/
│   ├── en-US.json
│   ├── es-ES.json
│   ├── fr-FR.json
├── nuxt.config.ts

Configuration example:

export default defineNuxtConfig({
  // ...
  i18n: {
    locales: [
      {
        code: 'en',
        file: 'en-US.json'
      },
      {
        code: 'es',
        file: 'es-ES.json'
      },
      {
        code: 'fr',
        file: 'fr-FR.json'
      }
    ],
    lazy: true,
    langDir: 'lang',
    defaultLocale: 'en'
  },
  // ...
})

Multiple files lazy loading

The files can load lazily multiple files.

This is useful because it is efficient to manage multiple files that define only differences without duplicating locale messages.

For example, let’s think for the case of Spanish language supporting. According to wikipedia, there are 20 countries where Spanish is spoken as an official language!

If these countries use all using file, that’s so hard to maintain because of the duplication of locale messages for each contry.

In the such case, we can maintain locale messages as common for target language, and define differential locale messages for each country, which is easier to maintain.

The following is a lang directory example of Spanish language defined as a file:

nuxt-project/
├── lang/
│   ├── es.json     # locale messages for common Spanish
│   ├── es-AR.json  # locale messages for Argentina
│   ├── es-UY.json  # locale messages for Uruguay
│   ├── es-US.json  # locale messages for Estados Unidos
|   ...             # other contries ...
├── nuxt.config.ts

The following is an config example of nuxt.confg.ts:

export default defineNuxtConfig({
  // ...
  i18n: {
    locales: [
      // ...
      /**
       * Example definition with `files` for a country with Spanish
       */
      {
        code: 'es-AR',
        name: 'Español (Argentina)',
        // lazy loading order: `es.json` -> `es-AR.json`, and then merge 'es-AR.json' to 'es.json'
        files: ['es.json', 'es-AR.json']
      },
      {
        code: 'es-UY',
        name: 'Español (Uruguay)',
        // lazy loading order: `es.json` -> `es-UY.json`, and then merge 'es-UY.json' to 'es.json'
        files: ['es.json', 'es-UY.json']
      },
      {
        code: 'es-US',
        name: 'Español (Estados Unidos)',
        // lazy loading order: `es.json` -> `es-US.json`, and then merge 'es-US.json' to 'es.json'
        files: ['es.json', 'es-US.json']
      },
      // ...
    ],
    lazy: true,
    langDir: 'lang',
    defaultLocale: 'en',
    vueI18n: {
      // If fallback is needed, you need to define
      fallbackLocale: 'en',
    }
  },
  // ...
})

Attention the files, so the above configuration specifies multiple file names.

@nuxtjs/i18n will load locale messages with lazy loading in the order of the array specified in files. It then overrides the locale messages in the order in which they were loaded.

In the above es-AR example, it has es.json and es-AR.json into files. In this case, @nuxtjs/i18n lazy-load es.json, and the it lazy-load es-AR.json and overrides for es.json locale messages.

In the example above, only two files are defined for files, of course you can specify more files over 2 files. In that case, the files will be loaded and override in array order too.

By taking advantage of the characteristic that locale messages are override with sequence, it's possible to manage locale messages by defining them on a differential basis. By putting common locale messages at the first of files, and then putting differ of locale messages in the order in files, it's possible to manage resources while avoiding duplication of locale messages.