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 totrue
(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 afile
orfiles
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 anObject
.
file
or files
is still not supported function
, PromisesBasic 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' }, // ...})
json
,json5
and yaml
are supported only.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.
files
or other locales
entries, once loaded, it will be used from cache.