@rushstack/webpack4-localization-plugin 0.15.15 → 0.15.18

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.29.2"
+      "packageVersion": "7.29.5"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rushstack/webpack4-localization-plugin",
-  "version": "0.15.15",
+  "version": "0.15.18",
   "description": "This plugin facilitates localization with Webpack.",
   "main": "lib/index.js",
   "typings": "dist/webpack4-localization-plugin.d.ts",
@@ -11,7 +11,7 @@
     "directory": "webpack/webpack4-localization-plugin"
   },
   "peerDependencies": {
-    "@rushstack/set-webpack-public-path-plugin": "^3.3.59",
+    "@rushstack/set-webpack-public-path-plugin": "^3.3.62",
     "@types/webpack": "^4.39.0",
     "webpack": "^4.31.0"
   },
@@ -24,8 +24,8 @@
     }
   },
   "dependencies": {
-    "@rushstack/localization-utilities": "0.8.15",
-    "@rushstack/node-core-library": "3.50.2",
+    "@rushstack/localization-utilities": "0.8.18",
+    "@rushstack/node-core-library": "3.51.1",
     "@types/node": "12.20.24",
     "@types/tapable": "1.0.6",
     "loader-utils": "~1.1.0",
@@ -34,9 +34,9 @@
   },
   "devDependencies": {
     "@rushstack/eslint-config": "3.0.0",
-    "@rushstack/heft": "0.47.3",
-    "@rushstack/heft-node-rig": "1.10.3",
-    "@rushstack/set-webpack-public-path-plugin": "3.3.59",
+    "@rushstack/heft": "0.47.5",
+    "@rushstack/heft-node-rig": "1.10.6",
+    "@rushstack/set-webpack-public-path-plugin": "3.3.62",
     "@types/loader-utils": "1.1.3",
     "@types/lodash": "4.14.116",
     "@types/minimatch": "3.0.5",
@@ -46,6 +46,5 @@
   "scripts": {
     "build": "heft build --clean",
     "_phase:build": "heft build --clean"
-  },
-  "readme": "# @rushstack/webpack4-localization-plugin\n\n## Installation\n\n`npm install @rushstack/webpack4-localization-plugin --save-dev`\n\n## Overview\n\nThis Webpack plugin produces bundles that have multiple locales' variants of strings embedded. It also\nhas out-of-box support for RESX files in addition to JSON strings files (with the extension `.loc.json`), including\nsupport for generating typings.\n\n### Example Plugin Usage\n\nThere are three example projects in this repository that make use of this plugin:\n\n- [Project 1](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-01)\n  - This project contains two webpack entrypoints (one with an async chunk, one without), without any localized\n    resources\n  - The output is a single, non-localized variant\n- [Project 2](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-02)\n  - This project contains three webpack entrypoints:\n    - [`indexA.ts`](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-02/src/indexA.ts)\n      directly references two `.loc.json` files and one `.resx` file, and dynamically imports an async chunk with\n      localized data, and an async chunk without localized data\n    - [`indexB.ts`](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-02/src/indexB.ts)\n      directly references two `.loc.json` files\n    - [`indexC.ts`](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-02/src/indexC.ts)\n      directly references no localized resources, and dynamically imports an async chunk without localized data\n  - The webpack config contains and references Spanish translations for most of the English strings in the resource files\n  - The output contains English, Spanish, and \"passthrough\" localized variants of files that contain\n    localized data, and a non-localized variant of the files that do not contain localized data\n- [Project 3](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-03)\n  - This project contains four webpack entrypoints:\n    - [`indexA.ts`](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-03/src/indexA.ts)\n      directly references one `.loc.json` file, one `.resx.json` file, one `.resx` file, and one `.resjson` file, and dynamically imports an async chunk with\n      localized data, and an async chunk without localized data\n    - [`indexB.ts`](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-03/src/indexB.ts)\n      directly references one `.loc.json` file and one `.resx.json` file\n    - [`indexC.ts`](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-03/src/indexC.ts)\n      directly references no localized resources, and dynamically imports an async chunk with localized data\n    - [`indexD.ts`](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-03/src/indexD.ts)\n      directly references no localized resources, and dynamically imports an async chunk without localized data\n  - The webpack config contains or references Spanish translations for some of the English strings in the resource files\n  - The output contains English, Spanish, \"passthrough,\" and two pseudo-localized variants of files that contain\n    localized data, and a non-localized variant of the files that do not contain localized data\n\n### `.resx` vs `.loc.json` vs `.resjson`\n\n[`.resx`](https://docs.microsoft.com/en-us/dotnet/framework/resources/creating-resource-files-for-desktop-apps#resources-in-resx-files)\nis an XML format for resource data. It is primarily used in .NET development, and it is supported by\nsome translation services. See an example of a `.resx` file\n[here](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-02/src/strings5.resx).\nNote that the `<xsd:schema>` and `<resheader>` elements are not required. Also note that although the\n`.resx` supports many different types of localized data including strings and binary data, **only strings**\nare supported by this plugin.\n\n`.loc.json` is a very simple `JSON` schema for specifying localized string and translator comments.\nSee an example of a `.loc.json` file\n[here](https://github.com/microsoft/rushstack/tree/main/build-tests/localization-plugin-test-02/src/strings3.loc.json).\n\n`.resjson` is another simple `JSON` schema for specifying localized string and translator comments.\nSee [here](https://lingohub.com/developers/resource-files/resjson-localization) for documentation on `.resjson`\n\nFor most projects, `.loc.json` is a simpler format to use. However for large projects, projects that already use\ntranslation services that support `.resx`, or engineers who are already experienced .NET developers, `.resx`\nmay be more convenient.\n\n# Plugin\n\nTo use the plugin, add it to the `plugins` array of your Webpack config. For example:\n\n```JavaScript\nimport { LocalizationPlugin } from '@rushstack/webpack4-localization-plugin';\n\n{\n  plugins: [\n    new LocalizationPlugin( /* options */ )\n  ]\n}\n```\n\n***A note about the dev server:*** When Webpack is being run by the Webpack dev server, this plugin pipes\nthe strings in the loc files in the source (the `.loc.json` and the `.resx` files) to the output without\nany translations.\n\n## Options\n\n### `localizedData = { }`\n\n#### `localizedData.defaultLocale = { }`\n\nThis option has a required property (`localeName`), to specify the name of the locale used in the\n`.resx` and `.loc.json` files in the source.\n\n##### `localizedData.defaultLocale.fillMissingTranslationStrings = true | false`\n\nIf this option is set to `true`, strings that are missing from `localizedData.translatedStrings` will be\nprovided by the default locale (the strings in the `.resx` and `.loc.json` files in the source). If\nthis option is unset or set to `false`, an error will be emitted if a string is missing from\n`localizedData.translatedStrings`.\n\n#### `localizedData.translatedStrings = { }`\n\nThis option is used to specify the localization data to be used in the build. This object has the following\nstructure:\n\n- Locale name\n  - Compilation context-relative or absolute localization file path\n    - Translated strings\n\nFor example:\n\n```JavaScript\ntranslatedStrings: {\n  \"en-us\": {\n    \"./src/strings1.loc.json\": {\n      \"string1\": \"the first string\"\n    }\n  },\n  \"es-es\": {\n    \"./src/strings1.loc.json\": {\n      \"string1\": \"la primera cadena\"\n    }\n  }\n}\n```\n\nAlternatively, instead of directly specifying the translations, a path to a translated resource file can be\nspecified. For example:\n\n```JavaScript\ntranslatedStrings: {\n  \"en-us\": {\n    \"./src/strings1.loc.json\": \"./localization/en-us/strings1.loc.json\"\n  },\n  \"es-es\": {\n    \"./src/strings1.loc.json\": \"./localization/es-es/strings1.loc.json\"\n  }\n}\n```\n\n#### `localizedData.resolveMissingTranslatedStrings = (locales: string[], filePath: string) => { ... }`\n\nThis optional option can be used to resolve translated data that is missing from data that is provided\nin the `localizedData.translatedStrings` option. Set this option with a function expecting two parameters:\nthe first, an array of locale names, and second, a fully-qualified path to the localized file in source. The\nfunction should return an object with locale names as keys and localized data as values. The localized data\nvalue should either be:\n\n- a string: The absolute path to the translated data in `.resx` or `.loc.json` format\n- an object: An object containing the translated data\n\nNote that these values are the same as the values that can be specified for translations for a localized\nresource in `localizedData.translatedStrings`.\n\nIf the function returns data that is missing locales or individual strings, the plugin will fall back to the\ndefault locale if `localizedData.defaultLocale.fillMissingTranslationStrings` is set to `true`. If\n`localizedData.defaultLocale.fillMissingTranslationStrings` is set to `false`, an error will result.\n\n#### `localizedData.passthroughLocale = { }`\n\nThis option is used to specify how and if a passthrough locale should be generated. A passthrough locale\nis a generated locale in which each string's value is its name. This is useful for debugging and for identifying\ncases where a locale is missing.\n\nThis option takes two optional properties:\n\n##### `localizedData.passthroughLocale.usePassthroughLocale = true | false`\n\nIf `passthroughLocale.usePassthroughLocale` is set to `true`, a passthrough locale will be included in the output.\nBy default, the passthrough locale's name is \"passthrough.\"\n\n##### `localizedData.passthroughLocale.passthroughLocaleName = '...'`\n\nIf `passthroughLocale.usePassthroughLocale` is set to `true`, the \"passthrough\" locale name can be overridden\nby setting a value on `passthroughLocale.passthroughLocaleName`.\n\n#### `localizedData.pseudolocales = { }`\n\nThis option allows pseudolocales to be generated from the strings in the default locale. This option takes\nan option with pseudolocales as keys and options for the\n[pseudolocale package](https://www.npmjs.com/package/pseudolocale) as values.\n\n#### `localizedData.normalizeResxNewlines = 'crlf' | 'lf'`\n\nThis option allows normalization of newlines in RESX files. RESX files are XML, so newlines can be\nspecified by including a newline in the `<value>` element. For files stored on source control systems,\nclones on Windows can end up with CRLF newlines and clones on 'nix operating systems can end up with LF\nnewlines. This option can be used to help make compilations run on different platforms produce the same\nresult.\n\n#### `localizedData.ignoreMissingResxComments = true | false | undefined\n\nIf set to true, do not warn on missing RESX <data> element comments.\n\n### `globsToIgnore = [ ]`\n\nThis option is used to specify `.resx` and `.loc.json` files that should not be processed by this plugin.\nBy default, every `.resx`, `.resx.json`, and `.loc.json` file import is intercepted by this plugin, and an\nerror occurs if translations aren't provided for an intercepted file and the\n`localizedData.defaultLocale.fillMissingTranslationStrings` option is set to falsy, or if the\nfile is in an unexpected format. To avoid an error, specify files that should be ignored by this plugin in\nthis property. This is useful if a dependency uses files with a `.resx`, `.resx.json`, or `.loc.json`\nextension, but are processed in a different way from how this plugin handles localization.\nFor example: `globsToIgnore: [ 'node_modules/some-dependency-name/lib/**/*.loc.json' ]`\n\n### `noStringsLocaleName = '...'`\n\nThe value to replace the `[locale]` token with for chunks without localized strings. Defaults to \"none\"\n\n### `localizationStats = { }`\n\n#### `localizationStats.dropPath = '...'`\n\nThis option is used to designate a path at which a JSON file describing the localized assets produced should be\nwritten. If this property is omitted, the stats file won't be written.\n\nThe file has the following format:\n\n```JSON\n{\n  \"entrypoints\": {\n    \"<BUNDLE NAME>\": {\n      \"localizedAssets\": {\n        \"<LOCALE NAME>\": \"<ASSET NAME>\",\n        \"<LOCALE NAME>\": \"<ASSET NAME>\"\n      }\n    },\n    \"<BUNDLE NAME>\": {\n      \"localizedAssets\": {\n        \"<LOCALE NAME>\": \"<ASSET NAME>\",\n        \"<LOCALE NAME>\": \"<ASSET NAME>\"\n      }\n    }\n  },\n  \"namedChunkGroups\": {\n    \"<CHUNK NAME>\": {\n      \"localizedAssets\": {\n        \"<LOCALE NAME>\": \"<ASSET NAME>\",\n        \"<LOCALE NAME>\": \"<ASSET NAME>\"\n      }\n    },\n    \"<CHUNK NAME>\": {\n      \"localizedAssets\": {\n        \"<LOCALE NAME>\": \"<ASSET NAME>\",\n        \"<LOCALE NAME>\": \"<ASSET NAME>\"\n      }\n    }\n  }\n}\n\n```\n\n#### `localizationStats.callback = (stats) => { ... }`\n\nThis option is used to specify a callback to be called with the stats data that would be dropped at\n[`localizationStats.dropPath`](#localizationStats.DropPath--) after compilation completes.\n\n### `typingsOptions = { }`\n\nThis option is used to specify how and if TypeScript typings should be generated for loc files.\n\nIt takes two options:\n\n#### `typingsOptions.generatedTsFolder = '...'`\n\nThis property specifies the folder in which `.d.ts` files for loc files should be dropped. It is recommended\nthat this be a folder parallel to the source folder, specified in addition to the source folder in the\n[`rootDirs` `tsconfig.json` option](https://www.typescriptlang.org/docs/handbook/compiler-options.html).\n**The folder specified by this option is emptied when compilation is started.**\n\nThis property is required if `typingsOptions` is set.\n\n#### `typingsOptions.sourceRoot = '...'`\n\nThis optional property overrides the compiler context for discovery of localization files for which\ntypings should be generated.\n\n#### `typingsOptions.exportAsDefault = true | false`\n\nIf this option is set to `true`, loc modules typings will be exported wrapped in a `default` property. This\nallows strings to be imported by using the `import strings from './strings.loc.json';` syntax instead of\nthe `import { string1 } from './strings.loc.json';` or the `import * as strings from './strings.loc.json';`\nsyntax. This option is not recommended.\n\n## Links\n\n- [CHANGELOG.md](https://github.com/microsoft/rushstack/blob/main/webpack/localization-plugin/CHANGELOG.md) - Find\n  out what's new in the latest version\n\n`@rushstack/webpack4-localization-plugin` is part of the [Rush Stack](https://rushstack.io/) family of projects.\n"
+  }
 }