npm install @rushstack/webpack4-localization-plugin --save-dev

This Webpack plugin produces bundles that have multiple locales' variants of strings embedded. It alsohas out-of-box support for RESX files in addition to JSON strings files (with the extension.loc.json), includingsupport for generating typings.

There are three example projects in this repository that make use of this plugin:

• Project 1
  • This project contains two webpack entrypoints (one with an async chunk, one without), without any localizedresources
  • The output is a single, non-localized variant
• Project 2
  • This project contains three webpack entrypoints:
    • indexA.tsdirectly references two.loc.json files and one.resx file, and dynamically imports an async chunk withlocalized data, and an async chunk without localized data
    • indexB.tsdirectly references two.loc.json files
    • indexC.tsdirectly references no localized resources, and dynamically imports an async chunk without localized data
  • The webpack config contains and references Spanish translations for most of the English strings in the resource files
  • The output contains English, Spanish, and "passthrough" localized variants of files that containlocalized data, and a non-localized variant of the files that do not contain localized data
• Project 3
  • This project contains four webpack entrypoints:
    • indexA.tsdirectly references one.loc.json file, one.resx.json file, one.resx file, and one.resjson file, and dynamically imports an async chunk withlocalized data, and an async chunk without localized data
    • indexB.tsdirectly references one.loc.json file and one.resx.json file
    • indexC.tsdirectly references no localized resources, and dynamically imports an async chunk with localized data
    • indexD.tsdirectly references no localized resources, and dynamically imports an async chunk without localized data
  • The webpack config contains or references Spanish translations for some of the English strings in the resource files
  • The output contains English, Spanish, "passthrough," and two pseudo-localized variants of files that containlocalized data, and a non-localized variant of the files that do not contain localized data

.resxis an XML format for resource data. It is primarily used in .NET development, and it is supported bysome translation services. See an example of a.resx filehere.Note that the<xsd:schema> and<resheader> elements are not required. Also note that although the.resx supports many different types of localized data including strings and binary data,only stringsare supported by this plugin.

.loc.json is a very simpleJSON schema for specifying localized string and translator comments.See an example of a.loc.json filehere.

.resjson is another simpleJSON schema for specifying localized string and translator comments.Seehere for documentation on.resjson

For most projects,.loc.json is a simpler format to use. However for large projects, projects that already usetranslation services that support.resx, or engineers who are already experienced .NET developers,.resxmay be more convenient.

To use the plugin, add it to theplugins array of your Webpack config. For example:

import{LocalizationPlugin}from'@rushstack/webpack4-localization-plugin';{plugins:[newLocalizationPlugin(/* options */)]}

A note about the dev server: When Webpack is being run by the Webpack dev server, this plugin pipesthe strings in the loc files in the source (the.loc.json and the.resx files) to the output withoutany translations.

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.

If this option is set totrue, strings that are missing fromlocalizedData.translatedStrings will beprovided by the default locale (the strings in the.resx and.loc.json files in the source). Ifthis option is unset or set tofalse, an error will be emitted if a string is missing fromlocalizedData.translatedStrings.

This option is used to specify the localization data to be used in the build. This object has the followingstructure:

• Locale name
  • Compilation context-relative or absolute localization file path
    • Translated strings

For example:

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 bespecified. For example:

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"}}

This optional option can be used to resolve translated data that is missing from data that is providedin thelocalizedData.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. Thefunction should return an object with locale names as keys and localized data as values. The localized datavalue should either be:

• a string: The absolute path to the translated data in.resx or.loc.json format
• an object: An object containing the translated data

Note that these values are the same as the values that can be specified for translations for a localizedresource inlocalizedData.translatedStrings.

If the function returns data that is missing locales or individual strings, the plugin will fall back to thedefault locale iflocalizedData.defaultLocale.fillMissingTranslationStrings is set totrue. IflocalizedData.defaultLocale.fillMissingTranslationStrings is set tofalse, an error will result.

This option is used to specify how and if a passthrough locale should be generated. A passthrough localeis a generated locale in which each string's value is its name. This is useful for debugging and for identifyingcases where a locale is missing.

This option takes two optional properties:

IfpassthroughLocale.usePassthroughLocale is set totrue, a passthrough locale will be included in the output.By default, the passthrough locale's name is "passthrough."

IfpassthroughLocale.usePassthroughLocale is set totrue, the "passthrough" locale name can be overriddenby setting a value onpassthroughLocale.passthroughLocaleName.

This option allows pseudolocales to be generated from the strings in the default locale. This option takesan option with pseudolocales as keys and options for thepseudolocale package as values.

This option allows normalization of newlines in RESX files. RESX files are XML, so newlines can bespecified by including a newline in the<value> element. For files stored on source control systems,clones on Windows can end up with CRLF newlines and clones on 'nix operating systems can end up with LFnewlines. This option can be used to help make compilations run on different platforms produce the sameresult.

If set to true, do not warn on missing RESX element comments.

This option is used to specify.resx and.loc.json files that should not be processed by this plugin.By default, every.resx,.resx.json, and.loc.json file import is intercepted by this plugin, and anerror occurs if translations aren't provided for an intercepted file and thelocalizedData.defaultLocale.fillMissingTranslationStrings option is set to falsy, or if thefile is in an unexpected format. To avoid an error, specify files that should be ignored by this plugin inthis property. This is useful if a dependency uses files with a.resx,.resx.json, or.loc.jsonextension, but are processed in a different way from how this plugin handles localization.For example:globsToIgnore: [ 'node_modules/some-dependency-name/lib/**/*.loc.json' ]

The value to replace the[locale] token with for chunks without localized strings. Defaults to "none"

This option is used to designate a path at which a JSON file describing the localized assets produced should bewritten. If this property is omitted, the stats file won't be written.

The file has the following format:

{"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>"      }    }  }}

This option is used to specify a callback to be called with the stats data that would be dropped atlocalizationStats.dropPath after compilation completes.

This option is used to specify how and if TypeScript typings should be generated for loc files.

It takes two options:

This property specifies the folder in which.d.ts files for loc files should be dropped. It is recommendedthat this be a folder parallel to the source folder, specified in addition to the source folder in therootDirstsconfig.json option.The folder specified by this option is emptied when compilation is started.

This property is required iftypingsOptions is set.

This optional property overrides the compiler context for discovery of localization files for whichtypings should be generated.

If this option is set totrue, loc modules typings will be exported wrapped in adefault property. Thisallows strings to be imported by using theimport strings from './strings.loc.json'; syntax instead oftheimport { string1 } from './strings.loc.json'; or theimport * as strings from './strings.loc.json';syntax. This option is not recommended.

• CHANGELOG.md - Findout what's new in the latest version

@rushstack/webpack4-localization-plugin is part of theRush Stack family of projects.