{"id":15716092,"url":"https://github.com/nossbigg/i18n-locales-loader","last_synced_at":"2026-04-28T08:34:49.323Z","repository":{"id":57270396,"uuid":"369750386","full_name":"nossbigg/i18n-locales-loader","owner":"nossbigg","description":"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.","archived":false,"fork":false,"pushed_at":"2021-05-26T22:22:39.000Z","size":752,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-08T08:43:18.001Z","etag":null,"topics":["i18n","locales","translations","webpack","webpack-loader"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nossbigg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-22T07:59:16.000Z","updated_at":"2021-05-26T22:22:14.000Z","dependencies_parsed_at":"2022-09-15T12:30:34.202Z","dependency_job_id":null,"html_url":"https://github.com/nossbigg/i18n-locales-loader","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nossbigg%2Fi18n-locales-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nossbigg%2Fi18n-locales-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nossbigg%2Fi18n-locales-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nossbigg%2Fi18n-locales-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nossbigg","download_url":"https://codeload.github.com/nossbigg/i18n-locales-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246379378,"owners_count":20767694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","locales","translations","webpack","webpack-loader"],"created_at":"2024-10-03T21:44:01.196Z","updated_at":"2026-04-28T08:34:42.913Z","avatar_url":"https://github.com/nossbigg.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# i18n-locales-loader\n\nA `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.\n\n[![npm version](https://badge.fury.io/js/i18n-locales-loader.svg)](https://badge.fury.io/js/i18n-locales-loader)\n\n## What it Does\n\n1. **Splits** a `locales.json` up into **separate files** for each locale.\n\n   - `locales.json`\n\n   ```javascript\n   == Before ==\n   // locales.json\n   {\n     \"en\": { \"common\": { \"hello\": \"Hello\" } },\n     \"zh\": { \"common\": { \"hello\": \"你好\" } }\n   }\n\n   == After ==\n   // locales/en.json\n   { \"en\": { \"common\": { \"hello\": \"Hello\" } } }\n\n   // locales/zh.json\n   { \"zh\": { \"common\": { \"hello\": \"你好\" } } }\n   ```\n\n   - Webpack Build Output\n\n   ```\n   == Before ==\n    - build\n      - static\n        - js\n          - main.a543vfds.chunk.js\n\n   == After ==\n    - build\n      - static\n        - js\n          - main.a543vfds.chunk.js\n        - locales\n          - src\n            - MyComponent\n              - en.a433v.json (en locale-specific translations)\n              - zh.kfd83.json (zh locale-specific translations)\n   ```\n\n2. **Modifies** `locales.json` imported object to return **URL paths** for each locale.\n\n   - `MyComponent.js`\n\n   ```javascript\n    // MyComponent.js\n    import locales from './locales.json'\n\n    == Before ==\n    // locales object\n    {\n      en: { common: { hello: \"Hello\" } },\n      zh: { common: { hello: \"你好\" } },\n    }\n\n    // locale usage\n    console.log(locales.en.common.hello) // prints \"Hello\"\n\n    == After ==\n    // locales object\n    {\n      en: \"/static/locales/src/MyComponent/en.a433v.json\",\n      zh: \"/static/locales/src/MyComponent/zh.kfd83.json\",\n    }\n\n    // locale usage\n    fetch(locales.en)\n      .then(resp =\u003e resp.json())\n      .then(content =\u003e console.log(content.en.common.hello)) // prints \"Hello\"\n   ```\n\n\u003cdetails markdown=\"1\"\u003e\n\u003csummary\u003eMore details\u003c/summary\u003e\n\n_Folder Structure:_\n\n```\n- \u003cproject root\u003e\n  - src\n    - MyComponent\n      - MyComponent.js\n      - locales.json\n\n```\n\n- `MyComponent.js` React component requries i18n translations\n- `locales.json` contains Component-specific translations\n\n\u003c/details\u003e\n\n### In Summary\n\n_Before:_\n\n- Loads `locales.json` as `Object` containing translations\n- Always loads translations for **all locales** via **JS code**\n- Translations are bundled **with JS code**\n\n_After:_\n\n- Loads `locales.json` as `Object` with **URL mappings to locale-specific translations** (eg. `en.json`, `zh.json`)\n- Option to load translations for **specific locales** via **XHR**\n- Translations are bundled separately from JS code as **static JSON assets**\n\n## Installation\n\n1. Add `i18n-locales-loader` dependency\n\n   ```bash\n   yarn add --dev i18n-locales-loader\n   or\n   npm install --save-dev i18n-locales-loader\n   ```\n\n1. Use `i18n-locales-loader` in `webpack.config.js`\n\n   ```javascript\n   // webpack.config.js\n\n   module.exports = {\n     module: {\n       rules: [\n         // other rules...\n         {\n           test: /locales\\.json$/,\n           type: \"javascript/auto\",\n           loader: require.resolve(\"i18n-locales-loader\"),\n           options: {\n             // for more details: see options documentation\n             esModule: true,\n             buildLocalesPath: [\"static\", \"locales\"],\n           },\n         },\n         // other rules...\n       ],\n     },\n   };\n\n   // note: need to define 'type' to override webpack v4 default JSON-loading behavior\n   ```\n\n## Loader `options`\n\n- `options.esModule`\n  - Optional, `boolean`, default: `true`\n  - Defines module output format\n  - When true, Emit output as ES Module (ie. `export default`)\n  - When false, Emit output as CommonJS Module (ie. `module.exports`)\n- `options.buildLocalesPath`\n  - Optional, `string[]`, default: `[\"static\", \"locales\"]`\n  - Defines build directory path to emit locales files to\n  - Uses [`path.join()`](https://nodejs.org/api/path.html#path_path_join_paths) to generate directory path\n  - eg. In default setup, `[\"static\", \"locales\"]` -\u003e `/static/locales`\n\n## Motivation\n\n1. How to load `locales` information?\n\n- ❌ Via component JS code (ie. larger component code \u003e larger initial bundle size \u003e more JS code to parse \u003e slower page load)\n- ✅ Via XHR instead (to take advantage of **lazy loading** and **HTTP caching**)\n\n2. How to load `locale-specific` information? (eg. `en`, `zh`)\n\n- ❌ Load all locales (bad, because a site will only use a single locale (or two at best, for fallback cases))\n- ✅ Load only specific locales that are required (less overall data to transfer)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnossbigg%2Fi18n-locales-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnossbigg%2Fi18n-locales-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnossbigg%2Fi18n-locales-loader/lists"}