Skip to content

Commit 5fbba31

Browse files
iclantoniclanton
committed
Include documentation.
1 parent 2fd3b15 commit 5fbba31

File tree

1 file changed

+159
-0
lines changed

1 file changed

+159
-0
lines changed

‎webpack/localization-plugin/README.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Localization Plugin for Webpack
2+
3+
## Installation
4+
5+
`npm install @rushstack/localization-plugin --save-dev`
6+
7+
## Overview
8+
9+
This plugin produces webpack bundles that have multiple locales' variants of strings embedded. It also
10+
has OOB support for RESX files in addition to JSON strings files (with the extension `.loc.json`), including
11+
support for generating typings.
12+
13+
# Plugin
14+
15+
To use the plugin, add it to the `plugins` array of your Webpack config. For example:
16+
17+
```JavaScript
18+
import { LocalizationPlugin } from '@rushstack/localization-plugin';
19+
20+
{
21+
plugins: [
22+
new SetPublicPathPlugin( /* webpackPublicPathOptions */ )
23+
]
24+
}
25+
```
26+
27+
***A note about the dev server:*** When Webpack is being run by the Webpack dev server, this plugin pipes
28+
the strings in the loc files in the source (the `.loc.json` and the `.resx` files) to the output without
29+
any translations.
30+
31+
## Options
32+
33+
### `localizedStrings = { }`
34+
35+
This option is used to specify the localization data to be used in the build. This object has the following
36+
structure:
37+
- Locale name
38+
- Compilation context-relative or absolute localization file path
39+
- Translated strings
40+
41+
For example:
42+
43+
```JavaScript
44+
localizedStrings: {
45+
"en-us": {
46+
"./src/strings1.loc.json": {
47+
"string1": "the first string"
48+
}
49+
},
50+
"es-es": {
51+
"./src/strings1.loc.json": {
52+
"string1": "la primera cadena"
53+
}
54+
}
55+
}
56+
```
57+
58+
### `passthroughLocale = { }`
59+
60+
This option is used to specify how and if a passthrough locale should be generated. A passthrough locale
61+
is a generated locale in which each string's value is its name. This is useful for debugging and for identifying
62+
cases where a locale is missing.
63+
64+
This option takes two optional properties:
65+
66+
#### `passthroughLocale.usePassthroughLocale = true | false`
67+
68+
If `passthroughLocale.usePassthroughLocale` is set to `true`, a passthrough locale will be included in the output.
69+
By default, the passthrough locale's name is "passthrough."
70+
71+
#### `passthroughLocale.passthroughLocaleName = '...'`
72+
73+
If `passthroughLocale.usePassthroughLocale` is set to `true`, the "passthrough" locale name can be overridden
74+
by setting a value on `passthroughLocale.passthroughLocaleName`.
75+
76+
### `exportAsDefault = true | false`
77+
78+
If this option is set to `true`, loc modules will be exported wrapped in a `default` property. This
79+
allows strings to be imported by using the `import strings from './strings.loc.json';` syntax instead of
80+
the `import { string1 } from './strings.loc.json';` or the `import * as strings from './strings.loc.json';`
81+
syntax.
82+
83+
### `filesToIgnore = [ ]`
84+
85+
This option is used to specify `.resx` and `.loc.json` files that should not be processed by this plugin.
86+
By default, every `.resx` and `.loc.json` file import is intercepted by this plugin, and an error occurs
87+
if translations aren't provided for an intercepted file. To avoid that error, list files that should be ignored
88+
by this plugin in this property. Files should be specified as either absolute paths or paths relative
89+
to the Webpack compilation context.
90+
91+
### `localizationStatsDropPath = '...'`
92+
93+
This option is used to designate a path at which a JSON file describing the localized assets produced should be
94+
written. If this property is omitted, the stats file won't be written.
95+
96+
The file has the following format:
97+
98+
```JSON
99+
{
100+
"entrypoints": {
101+
"<BUNDLE NAME>": {
102+
"localizedAssets": {
103+
"<LOCALE NAME>": "<ASSET NAME>",
104+
"<LOCALE NAME>": "<ASSET NAME>"
105+
}
106+
},
107+
"<BUNDLE NAME>": {
108+
"localizedAssets": {
109+
"<LOCALE NAME>": "<ASSET NAME>",
110+
"<LOCALE NAME>": "<ASSET NAME>"
111+
}
112+
}
113+
},
114+
"namedChunkGroups": {
115+
"<CHUNK NAME>": {
116+
"localizedAssets": {
117+
"<LOCALE NAME>": "<ASSET NAME>",
118+
"<LOCALE NAME>": "<ASSET NAME>"
119+
}
120+
},
121+
"<CHUNK NAME>": {
122+
"localizedAssets": {
123+
"<LOCALE NAME>": "<ASSET NAME>",
124+
"<LOCALE NAME>": "<ASSET NAME>"
125+
}
126+
}
127+
}
128+
}
129+
130+
```
131+
132+
### `localizationStatsCallback = (stats) => { ... }`
133+
134+
This option is used to specify a callback to be called with the stats data that would be dropped at
135+
[`localizationStatsDropPath`](#localizationStatsDropPath--) after compilation completes.
136+
137+
### `typingsOptions = { }`
138+
139+
This option is used to specify how and if TypeScript typings should be generated for loc files.
140+
141+
It takes two options:
142+
143+
#### `typingsOptions.generatedTsFolder = '...'`
144+
145+
This property specifies the folder in which `.d.ts` files for loc files should be dropped. It is recommended
146+
that this be a folder parallel to the source folder, specified in addition to the source folder in the
147+
[`rootDirs` `tsconfig.json` option](https://www.typescriptlang.org/docs/handbook/compiler-options.html).
148+
**The folder specified by this option is emptied when compilation is started.**
149+
150+
This property is required if `typingsOptions` is set.
151+
152+
#### `typingsOptions.sourceRoot = '...'`
153+
154+
This optional property overrides the compiler context for discovery of localization files for which
155+
typings should be generated.
156+
157+
# License
158+
159+
MIT (http://www.opensource.org/licenses/mit-license.php)

0 commit comments

Comments
 (0)