A webpack
loader that splits your locales.json
file into locale-specific files (eg. en.json
, zh.json
) for better locale-specific translations lazy loading support.
-
Splits a
locales.json
up into separate files for each locale.locales.json
== Before == // locales.json { "en": { "common": { "hello": "Hello" } }, "zh": { "common": { "hello": "你好" } } } == After == // locales/en.json { "en": { "common": { "hello": "Hello" } } } // locales/zh.json { "zh": { "common": { "hello": "你好" } } }
- Webpack Build Output
== Before == - build - static - js - main.a543vfds.chunk.js == After == - build - static - js - main.a543vfds.chunk.js - locales - src - MyComponent - en.a433v.json (en locale-specific translations) - zh.kfd83.json (zh locale-specific translations)
-
Modifies
locales.json
imported object to return URL paths for each locale.MyComponent.js
// MyComponent.js import locales from './locales.json' == Before == // locales object { en: { common: { hello: "Hello" } }, zh: { common: { hello: "你好" } }, } // locale usage console.log(locales.en.common.hello) // prints "Hello" == After == // locales object { en: "/static/locales/src/MyComponent/en.a433v.json", zh: "/static/locales/src/MyComponent/zh.kfd83.json", } // locale usage fetch(locales.en) .then(resp => resp.json()) .then(content => console.log(content.en.common.hello)) // prints "Hello"
More details
Folder Structure:
- <project root>
- src
- MyComponent
- MyComponent.js
- locales.json
MyComponent.js
React component requries i18n translationslocales.json
contains Component-specific translations
Before:
- Loads
locales.json
asObject
containing translations - Always loads translations for all locales via JS code
- Translations are bundled with JS code
After:
- Loads
locales.json
asObject
with URL mappings to locale-specific translations (eg.en.json
,zh.json
) - Option to load translations for specific locales via XHR
- Translations are bundled separately from JS code as static JSON assets
-
Add
i18n-locales-loader
dependencyyarn add --dev i18n-locales-loader or npm install --save-dev i18n-locales-loader
-
Use
i18n-locales-loader
inwebpack.config.js
// webpack.config.js module.exports = { module: { rules: [ // other rules... { test: /locales\.json$/, type: "javascript/auto", loader: require.resolve("i18n-locales-loader"), options: { // for more details: see options documentation esModule: true, buildLocalesPath: ["static", "locales"], }, }, // other rules... ], }, }; // note: need to define 'type' to override webpack v4 default JSON-loading behavior
options.esModule
- Optional,
boolean
, default:true
- Defines module output format
- When true, Emit output as ES Module (ie.
export default
) - When false, Emit output as CommonJS Module (ie.
module.exports
)
- Optional,
options.buildLocalesPath
- Optional,
string[]
, default:["static", "locales"]
- Defines build directory path to emit locales files to
- Uses
path.join()
to generate directory path - eg. In default setup,
["static", "locales"]
->/static/locales
- Optional,
- How to load
locales
information?
- ❌ Via component JS code (ie. larger component code > larger initial bundle size > more JS code to parse > slower page load)
- ✅ Via XHR instead (to take advantage of lazy loading and HTTP caching)
- How to load
locale-specific
information? (eg.en
,zh
)
- ❌ Load all locales (bad, because a site will only use a single locale (or two at best, for fallback cases))
- ✅ Load only specific locales that are required (less overall data to transfer)