Write some documentation

[PeterWone]

This is the official i18n method. The only material even remotely resembling documentation is a sample that won't even build.

I tried looking at the code. Considering that fundamentally all this does is dictionary base token replacement with the dictionary being selected by the locale, it is ridiculously convoluted and indirect. This probably makes it configurable and versatile, but that has absolutely no value if you don't tell people how to use the damn thing.

Write complete documentation. Now. Don't kid yourselves that it's open source and people should do it themselves. You have made your code far too indirect and complicated for that to happen.

From the readme.md

import * as nls from 'vscode-nls';

let localize = nls.config({ locale: 'de-DE' })();

console.log(localize('keyOne', "Hello World"));
console.log(localize('keyTwo', "Current Date {0}", Date.now()));

This is not documentation. It is the barest of sketches.

Inspection of the code reveals that an arbitrary number of parameters are accepted and from the above one can infer than these will be substituted in order for indexed tokens like {0} similar to C# string.Format. Can format specifiers be applied to control the rendering"? Will the rendering itself be localised for month and day names? Nobody knows because there's no documentation. I just noticed that this sample code explicitly specifies a locale. Super handy for testing. Pity nobody knows.

To what exactly does "keyOne" map? There's absolutely no indication.

Inspection of the code also reveals a conspicuous absence of comments. Even accepted PRs don't really say what they are. And things aren't what they seem. Depending on what happens earlier with the config method, localize might totally ignore the key field. It's so bad it makes me want to go add comments to my own code even though it hasn't been presented to millions as the endorsed solution.

Don't be lazy and give a quick sketch of the most common case. Explain ALL of the parameters, ALL the consequences of config choices and ALL the magic strings. If that seems like too much work then maybe your library should be simpler. Have a look at #18. The combination of complexity and dismal documentation is such a barrier to use that people found it less trouble to go write their own library.

[prantlf]

This should be closed as duplicate of #18.