eseq / i18next-loader

Webpack loader for client embedded i18next locales from json or yaml

@alienfast/i18next-loader

yarn add -D @alienfast/i18next-loader

This webpack loader generates the resources structure necessary for i18next. The structure is webpacked with the client bundle at build time, thus avoiding loading any language resources via extra HTTP requests.

Features

• glob based file filtering
• one to many overrides supporting reuse cases (white labeling)
• yaml and json support
• locale chunking (help wanted - see #6)

Given a locales directory, by default, the loader will find and parse any json|yaml|yml file and attribute the contents to the containing lang folder e.g. en. There is no need to add lang such as en or de inside your json or yaml files.

See the test/data directory for structure and example data.

Usage

Sample app structure

└── app
    └── src
    │  └── app.js
    └── locales
       ├── index.js
       ├── de
       │   ├── foo.json
       │   └── bar.yaml
       └── en
           ├── foo.json
           └── bar.yaml

Option 1: use with webpack.config.js (recommended)

module.exports = {
  // ... snip
  module: {
    rules: [
      {
        test: /locales/,
        loader: '@alienfast/i18next-loader',
        // options here
        //query: { overrides: [ '../node_modules/lib/locales' ] }
      }
    ]
  }
  // ... snip
}

// File: app.js
import i18n from 'i18next'
import resources from '../locales'  // typescript: import * as resources from '../locales'

i18n.init({
  resources
});

// Use the resources as documented on i18next.com
i18n.t('key')

Option 2: use with import syntax

// File: app.js
import i18n from 'i18next'
import resources from '@alienfast/i18next-loader!../locales/index.js'

i18n.init({
  resources
});

// Use the resources as documented on i18next.com
i18n.t('key')

And you're done! The index.js can be empty, it's just needed to point the loader to the root directory of the locales.

Advanced Usage

Options are set via the loader query. See webpack documentation for more details regarding how this mechanism works. The following examples assume you understand these values are used as the query value.

Filtering files

You can filter files in your file structure by specifying any glob supported by glob-all.

By default, any json|yaml|yml will be loaded.

Only json

{include: ['**/*.json']}

All json except one file

{include: ['**/*.json', '!**/excludeThis.json']}

Overriding/White labeling

Applications that reuse libraries e.g. white labeling, can utilize one to many sets of locale directories that the app will override.

{overrides: ['../node_modules/lib1/locales']}

This configures the loader to work on a file structure like the following:

└── app
    ├── src
    │  └── app.js
    ├── locales
    │  ├── index.js
    │  └── en
    │      ├── foo.json
    │      └── bar.yaml
    └── node_modules
        └── lib1
            └── locales
               ├── index.js
               └── en
                   ├── foo.json
                   └── bar.yaml

Everything from app/locales will override anything specified in one to many libraries.

Override path method

join | resolve | replace

join by default

join and replace is path methods with locales folder

{overridePathMethod: 'replace'}

Use file basename as the i18next namespace

{basenameAsNamespace: true}

The following file structure would result in resources loaded as below:

└── app
    ├── src
    │  └── app.js
    └── locales
       ├── index.js
       └── en
           ├── foo.json
           └── bar.yaml

foo.json

{
  "header": {
    "title": "TITLE"
  }
}

bar.yaml

footer:
  aboutUs: About us

Results in this object loaded:

"en": {
  "foo": {
    "header": {
      "title":"TITLE"
    }
  },
  "bar": {
    "footer":{
      "aboutUs":"About us"
    }
  }
}

Credit

This was forked from i18next-resource-store-loader because we changed it in breaking ways that are incompatible.
Thanks to the original authors and contributors.