No doc for localize

There's a sample but it's worthless if you can't read Japanese because who in their right mind would set the display language to a language they can't read while trying to figure out a library?

I'd be able to use it if the sample language were French but that still wouldn't be any use to people who can't read French.

FFS write one wiki page and give a narrative explaining what's where and why, especially the relationships between

• the method parameters key, message and the optional args
• the symbols
• the folders

For example, symbols "sayHello.text", and "extension.sayHello.title" both exist. I suspect "extension.sayHello.title" is used to locate symbols for the extension settings defined in package.json but where do I put the dictionary if I want localize to use it? Alternately how do I tell localize where to look?

I tried looking at the source code for the localize function but somebody wrote super clever code that dynamically overloads methods making it very hard to follow. Do NOT refer me to Stack Overflow, I asked about this on SO two years ago and have not received so much as a comment there.

UPDATE

It would also help if you emphasised the fact that attempts to add another language will fail until you register that language in gulp.js and run gulp build.

As you may have guessed I've finally figured out how to use it. But docs would help others.

But understanding the sample enough to add another language isn't enough. In both the sample and my own extension,

const localize = nls.config({ messageFormat: nls.MessageFormat.file })();

causes a call to a function loadMessageBundle(file), but in my extension this fails because the parameter is undefined. Spinning up the working sample and breakpointing the start of this function allows a look at the call stack, which eventually disappears into helper.js inside node.

The principal difference between my app and the sample, so far as I can tell, is webpack.

No doubt there is some action required to make webpack include something or other. One would expect this to be explained in the documentation in the wiki, but there isn't any.