@rushstack/webpack5-localization-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+@rushstack/webpack5-localization-plugin
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# @rushstack/webpack5-localization-plugin
+
+## Installation
+
+`npm install @rushstack/webpack5-localization-plugin --save-dev`
+
+## Overview
+
+This Webpack plugin produces bundles that have multiple locales' variants of strings embedded. It also
+has out-of-box support for RESX files in addition to JSON strings files (with the extensions `.loc.json` or `.resjson`).
+
+The loaders can also be chained with other loaders that convert the content to one of the known formats.
+
+# Plugin
+
+To use the plugin, add it to the `plugins` array of your Webpack config, and specify one or more loaders. For example:
+
+```JavaScript
+import { LocalizationPlugin } from '@rushstack/webpack5-localization-plugin';
+
+{
+  plugins: [
+    new LocalizationPlugin( /* options */ )
+  ],
+  module: {
+    rules: [{
+      test: /\.resjson$/,
+      use: {
+        // All loaders are available in `@rushstack/webpack5-localization-plugin/lib/loaders/`
+        // Loaders for specific formats: `resjson-loader`, `locjson-loader`, `resx-loader`
+        // Loader that switches on file extension: `loc-loader`
+        // Loader that switches on file extension and skips localization: `default-locale-loader`
+        loader: require.resolve('@rushstack/webpack5-localization-plugin/lib/loaders/resjson-loader')
+      },
+      // Can be one of `javascript/esm`, `javascript/dynamic`, or `json`
+      // `javascript/esm` will produce the smallest bundle sizes, while `json` will produce faster code for large string tables
+      type: 'javascript/esm',
+      sideEffects: false
+    }]
+  }
+}
+```
+
+***A note about the dev server:*** When Webpack is being run by the Webpack dev server, this plugin pipes
+the strings in the loc files in the source (the `.loc.json` and the `.resx` files) to the output without
+any translations.
+
+## Options
+
+### `localizedData = { }`
+
+#### `localizedData.defaultLocale = { }`
+
+This option has a required property (`localeName`), to specify the name of the locale used in the
+`.resx` and `.loc.json` files in the source.
+
+##### `localizedData.defaultLocale.fillMissingTranslationStrings = true | false`
+
+If this option is set to `true`, strings that are missing from `localizedData.translatedStrings` will be
+provided by the default locale (the strings in the `.resx` and `.loc.json` files in the source). If
+this option is unset or set to `false`, an error will be emitted if a string is missing from
+`localizedData.translatedStrings`.
+
+#### `localizedData.translatedStrings = { }`
+
+This option is used to specify the localization data to be used in the build. This object has the following
+structure:
+
+- Locale name
+  - Compilation context-relative or absolute localization file path
+    - Translated strings
+
+For example:
+
+```JavaScript
+translatedStrings: {
+  "en-us": {
+    "./src/strings1.loc.json": {
+      "string1": "the first string"
+    }
+  },
+  "es-es": {
+    "./src/strings1.loc.json": {
+      "string1": "la primera cadena"
+    }
+  }
+}
+```
+
+Alternatively, instead of directly specifying the translations, a path to a translated resource file can be
+specified. For example:
+
+```JavaScript
+translatedStrings: {
+  "en-us": {
+    "./src/strings1.loc.json": "./localization/en-us/strings1.loc.json"
+  },
+  "es-es": {
+    "./src/strings1.loc.json": "./localization/es-es/strings1.loc.json"
+  }
+}
+```
+
+#### `localizedData.resolveMissingTranslatedStrings = (locales: string[], filePath: string, context: LoaderContext<{}>) => { ... }`
+
+This optional option can be used to resolve translated data that is missing from data that is provided
+in the `localizedData.translatedStrings` option. Set this option with a function expecting two parameters:
+the first, an array of locale names, and second, a fully-qualified path to the localized file in source. The
+function should synchronously or asynchronously (as a promise) return an object (or map) with locale names as keys and localized
+data as values. The localized data value should be one of:
+
+- a string: The absolute path to the translated data in `.resx`, `.loc.json`, or `.resjson` format
+- an object: An object containing the translated data
+- a map: A map containing the translated data
+
+Note that these values are the same as the values that can be specified for translations for a localized
+resource in `localizedData.translatedStrings`.
+
+If the function returns data that is missing locales or individual strings, the plugin will fall back to the
+default locale if `localizedData.defaultLocale.fillMissingTranslationStrings` is set to `true`. If
+`localizedData.defaultLocale.fillMissingTranslationStrings` is set to `false`, an error will result.
+
+#### `localizedData.passthroughLocale = { }`
+
+This option is used to specify how and if a passthrough locale should be generated. A passthrough locale
+is a generated locale in which each string's value is its name. This is useful for debugging and for identifying
+cases where a locale is missing.
+
+This option takes two optional properties:
+
+##### `localizedData.passthroughLocale.usePassthroughLocale = true | false`
+
+If `passthroughLocale.usePassthroughLocale` is set to `true`, a passthrough locale will be included in the output.
+By default, the passthrough locale's name is "passthrough."
+
+##### `localizedData.passthroughLocale.passthroughLocaleName = '...'`
+
+If `passthroughLocale.usePassthroughLocale` is set to `true`, the "passthrough" locale name can be overridden
+by setting a value on `passthroughLocale.passthroughLocaleName`.
+
+#### `localizedData.pseudolocales = { }`
+
+This option allows pseudolocales to be generated from the strings in the default locale. This option takes
+an option with pseudolocales as keys and options for the
+[pseudolocale package](https://www.npmjs.com/package/pseudolocale) as values.
+
+### `noStringsLocaleName = '...'`
+
+The value to replace the `[locale]` token with for chunks without localized strings. Defaults to "none"
+
+### `runtimeLocaleExpression = '...'`
+
+A chunk of raw ECMAScript to inject into the webpack runtime to resolve the current locale at execution time. Allows
+multiple locales to share the same runtime chunk if it does not directly contain localized strings.
+
+### `localizationStats = { }`
+
+#### `localizationStats.dropPath = '...'`
+
+This option is used to designate a path at which a JSON file describing the localized assets produced should be
+written. If this property is omitted, the stats file won't be written.
+
+The file has the following format:
+
+```JSON
+{
+  "entrypoints": {
+    "<BUNDLE NAME>": {
+      "localizedAssets": {
+        "<LOCALE NAME>": "<ASSET NAME>",
+        "<LOCALE NAME>": "<ASSET NAME>"
+      }
+    },
+    "<BUNDLE NAME>": {
+      "localizedAssets": {
+        "<LOCALE NAME>": "<ASSET NAME>",
+        "<LOCALE NAME>": "<ASSET NAME>"
+      }
+    }
+  },
+  "namedChunkGroups": {
+    "<CHUNK NAME>": {
+      "localizedAssets": {
+        "<LOCALE NAME>": "<ASSET NAME>",
+        "<LOCALE NAME>": "<ASSET NAME>"
+      }
+    },
+    "<CHUNK NAME>": {
+      "localizedAssets": {
+        "<LOCALE NAME>": "<ASSET NAME>",
+        "<LOCALE NAME>": "<ASSET NAME>"
+      }
+    }
+  }
+}
+
+```
+
+#### `localizationStats.callback = (stats) => { ... }`
+
+This option is used to specify a callback to be called with the stats data that would be dropped at
+[`localizationStats.dropPath`](#localizationStats.DropPath--) after compilation completes.
+
+## Links
+
+- [CHANGELOG.md](https://github.com/microsoft/rushstack/blob/main/webpack/localization-plugin/CHANGELOG.md) - Find
+  out what's new in the latest version
+
+`@rushstack/webpack5-localization-plugin` is part of the [Rush Stack](https://rushstack.io/) family of projects.

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.25.2"
+    }
+  ]
+}

package/dist/webpack5-localization-plugin.d.ts

@@ -0,0 +1,274 @@
+import type { Chunk } from 'webpack';
+import type { Compiler } from 'webpack';
+import { ILocalizationFile } from '@rushstack/localization-utilities';
+import type { IPseudolocaleOptions } from '@rushstack/localization-utilities';
+import type { LoaderContext } from 'webpack';
+import type { WebpackPluginInstance } from 'webpack';
+
+/**
+ * @public
+ */
+export declare interface IDefaultLocaleOptions {
+    /**
+     * This required property specifies the name of the locale used in the
+     * `.resx`, `.loc.json`, and `.resjson` files in the source
+     */
+    localeName: string;
+    /**
+     * If this option is set to `true`, strings that are missing from
+     * `localizedData.translatedStrings` will be provided by the default locale
+     */
+    fillMissingTranslationStrings?: boolean;
+}
+
+/**
+ * @public
+ */
+export declare interface ILocaleData {
+    [locFilePath: string]: ILocaleFileData;
+}
+
+/**
+ * @public
+ */
+export declare interface ILocaleElementMap {
+    [locale: string]: string;
+}
+
+/**
+ * @public
+ * Accepted formats:
+ *  - A string containing the path to the translations in .resjson format (keys mapped directly to values)
+ *  - An object mapping keys directly to values
+ *  - A map mapping keys directly to values
+ */
+export declare type ILocaleFileData = string | ILocaleFileObject | ReadonlyMap<string, string>;
+
+/**
+ * @public
+ */
+export declare interface ILocaleFileObject {
+    [stringName: string]: string;
+}
+
+/**
+ * The options for localization.
+ *
+ * @public
+ */
+export declare interface ILocalizationPluginOptions {
+    /**
+     * Localization data.
+     */
+    localizedData: ILocalizedData;
+    /**
+     * This option is used to specify `.resx`, `.resx.json`, and `.loc.json` files that should not be processed by
+     * this plugin.
+     */
+    globsToIgnore?: string[];
+    /**
+     * The value to replace the [locale] token with for chunks without localized strings. Defaults to "none"
+     */
+    noStringsLocaleName?: string;
+    /**
+     * A chunk of javascript to use to get the current locale at runtime. If specified, allows the runtime chunk
+     * to be non-localized even if it has async localized chunks, as long as it does not directly contain strings.
+     */
+    runtimeLocaleExpression?: string;
+    /**
+     * Options for how localization stats data should be produced.
+     */
+    localizationStats?: ILocalizationStatsOptions;
+}
+
+/**
+ * @public
+ */
+export declare interface ILocalizationStats {
+    entrypoints: {
+        [name: string]: ILocalizationStatsEntrypoint;
+    };
+    namedChunkGroups: {
+        [name: string]: ILocalizationStatsChunkGroup;
+    };
+}
+
+/**
+ * @public
+ */
+export declare interface ILocalizationStatsChunkGroup {
+    localizedAssets: ILocaleElementMap;
+}
+
+/**
+ * @public
+ */
+export declare interface ILocalizationStatsEntrypoint {
+    localizedAssets: ILocaleElementMap;
+}
+
+/**
+ * Options for how localization stats data should be produced.
+ *
+ * @public
+ */
+export declare interface ILocalizationStatsOptions {
+    /**
+     * This option is used to designate a path at which a JSON file describing the localized
+     * assets produced should be written.
+     */
+    dropPath?: string;
+    /**
+     * This option is used to specify a callback to be called with the stats data that would be
+     * dropped at `localizationStats.dropPath` after compilation completes.
+     */
+    callback?: (stats: ILocalizationStats) => void;
+}
+
+/**
+ * @public
+ */
+export declare interface ILocalizedData {
+    /**
+     * Options for the locale used in the source localized data files.
+     */
+    defaultLocale: IDefaultLocaleOptions;
+    /**
+     * Use this parameter to specify the translated data.
+     */
+    translatedStrings: ILocalizedStrings;
+    /**
+     * Use this parameter to specify a function used to load translations missing from
+     * the {@link ILocalizedData.translatedStrings} parameter.
+     */
+    resolveMissingTranslatedStrings?: (locales: string[], localizedFileKey: string, loaderContext: LoaderContext<{}>) => Promise<IResolvedMissingTranslations> | IResolvedMissingTranslations;
+    /**
+     * Options around including a passthrough locale.
+     */
+    passthroughLocale?: IPassthroughLocaleOptions;
+    /**
+     * Options for pseudo-localization.
+     */
+    pseudolocales?: IPseudolocalesOptions;
+}
+
+/**
+ * @public
+ */
+export declare interface ILocalizedStrings {
+    [locale: string]: ILocaleData;
+}
+
+/**
+ * @public
+ */
+export declare interface ILocalizedWebpackChunk extends Chunk {
+    localizedFiles?: {
+        [locale: string]: string;
+    };
+}
+
+/**
+ * Options for the passthrough locale.
+ *
+ * @public
+ */
+export declare interface IPassthroughLocaleOptions {
+    /**
+     * If this is set to `true`, a passthrough locale will be included in the output
+     */
+    usePassthroughLocale?: boolean;
+    /**
+     * If {@link IPassthroughLocaleOptions.usePassthroughLocale} is set, use this name for the passthrough locale.
+     * Defaults to "passthrough"
+     */
+    passthroughLocaleName?: string;
+}
+
+/**
+ * Options for generated pseudolocales.
+ *
+ * @public
+ */
+export declare interface IPseudolocalesOptions {
+    [pseudoLocaleName: string]: IPseudolocaleOptions;
+}
+
+/**
+ * @public
+ */
+export declare type IResolvedMissingTranslations = ReadonlyMap<string, ILocaleFileData>;
+
+/**
+ * @public
+ */
+export declare interface _IStringPlaceholder {
+    /**
+     * The literal string that will be injected for later replacement.
+     */
+    value: string;
+    /**
+     * The identifier for this particular placeholder, for lookup.
+     */
+    suffix: string;
+    /**
+     * The values of this string in each output locale.
+     */
+    valuesByLocale: Map<string, string>;
+    /**
+     * The key used to identify the source file containing the string.
+     */
+    locFilePath: string;
+    /**
+     * The identifier of the string within its original source file.
+     */
+    stringName: string;
+}
+
+/**
+ * This plugin facilitates localization in webpack.
+ *
+ * @public
+ */
+export declare class LocalizationPlugin implements WebpackPluginInstance {
+    private readonly _stringKeys;
+    private readonly _options;
+    private readonly _resolvedTranslatedStringsFromOptions;
+    private _stringPlaceholderCounter;
+    private readonly _stringPlaceholderMap;
+    private _passthroughLocaleName;
+    private _defaultLocale;
+    private _noStringsLocaleName;
+    private _fillMissingTranslationStrings;
+    private readonly _pseudolocalizers;
+    /**
+     * The outermost map's keys are the locale names.
+     * The middle map's keys are the resolved, file names.
+     * The innermost map's keys are the string identifiers and its values are the string values.
+     */
+    private _resolvedLocalizedStrings;
+    constructor(options: ILocalizationPluginOptions);
+    /**
+     * Apply this plugin to the specified webpack compiler.
+     */
+    apply(compiler: Compiler): void;
+    /**
+     * @public
+     *
+     * @returns An object mapping the string keys to placeholders
+     */
+    addDefaultLocFileAsync(context: LoaderContext<{}>, localizedFileKey: string, localizedResourceData: ILocalizationFile): Promise<Record<string, string>>;
+    /**
+     * @public
+     */
+    getPlaceholder(localizedFileKey: string, stringName: string): _IStringPlaceholder | undefined;
+    /**
+     * @internal
+     */
+    getDataForSerialNumber(serialNumber: string): _IStringPlaceholder | undefined;
+    private _addLocFileAndGetPlaceholders;
+    private _addTranslations;
+    private _initializeAndValidateOptions;
+}
+
+export { }

package/lib/AssetProcessor.d.ts

@@ -0,0 +1,26 @@
+import type { Asset, Chunk, Compilation, sources } from 'webpack';
+import type { LocalizationPlugin } from './LocalizationPlugin';
+export interface IProcessAssetOptionsBase {
+    plugin: LocalizationPlugin;
+    compilation: Compilation;
+    chunk: Chunk;
+    asset: Asset;
+}
+export interface IProcessNonLocalizedAssetOptions extends IProcessAssetOptionsBase {
+    fileName: string;
+    noStringsLocaleName: string;
+}
+export interface IProcessLocalizedAssetOptions extends IProcessAssetOptionsBase {
+    locales: Set<string>;
+    fillMissingTranslationStrings: boolean;
+    defaultLocale: string;
+    filenameTemplate: Parameters<typeof Compilation.prototype.getAssetPath>[0];
+}
+export interface IProcessAssetResult {
+    filename: string;
+    asset: sources.Source;
+}
+export declare const PLACEHOLDER_REGEX: RegExp;
+export declare function processLocalizedAsset(options: IProcessLocalizedAssetOptions): Record<string, string>;
+export declare function processNonLocalizedAsset(options: IProcessNonLocalizedAssetOptions): void;
+//# sourceMappingURL=AssetProcessor.d.ts.map

package/lib/AssetProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssetProcessor.d.ts","sourceRoot":"","sources":["../src/AssetProcessor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAa,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,sBAAsB,CAAC;AAoCnF,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAC;IACzB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,gCAAiC,SAAQ,wBAAwB;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,6BAA8B,SAAQ,wBAAwB;IAC7E,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,6BAA6B,EAAE,OAAO,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,iBAAiB,EAAE,MAG/B,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,6BAA6B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmEpG;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,gCAAgC,GAAG,IAAI,CAqCxF"}