microsoft / vscode-nls

npm module to support externalization and localization of VSCode extensions.

vscode-nls

⚠️ This package is no longer receiving new features in favor of the new localization library, vscode-l10n. Please use that collection of libraries instead.

CommonJS module to support externalization and localization. The module only depends on Node.js however its primary use case is for VSCode extensions.

Usage

// This must be the first import in the main entry file
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()));

The config call configures the nls module and should only be called once in the applications entry point. You pass in the locale you want to use and whether the resolved locale should be cached for all further calls. The config call returns a function which is used to load a message bundle. During development time the argument should stay empty. There is another tool that helps extracting the message from your sources and it creates the message bundles automatically for you. The tool is available here.

In secondary modules loaded from the 'main' module no configuration is necessary. However you still need to load the nls module and load the message bundle. This looks like this:

// In secondary file this import can be at random places.
import * as nls from 'vscode-nls';

let localize = nls.loadMessageBundle();

console.log(localize('keyOne', "Hello World"));

During development time the strings in the code are presented to the user. If the locale is set to 'pseudo' the messages are modified in the following form:

• vowels are doubled
• the string is prefixed with '\uFF3B' (Unicode zenkaku representation for [) and postfixed with '\uFF3D' (Unicode zenkaku representation for ])

History

5.2.0

• Removes injection mechanism due to breaking extensions. Please see Issue #44 for more details.

5.1.0

• Enable a mechanism for something to inject data into vscode-nls. This will be used by VS Code to inject translations into the nls module so that vscode-nls can work in the web. Context in this PR.

5.0.1

• Fixes null check in nls.config({...}) on web. Context in this PR by @a-stewart
• Misc dependency upgrades

5.0.0

• Split code into common, node and browser to support using vscode-nls in a Web browser. This is a breaking change and need adoption since the default exports of the module are only exporting the common types. To import the node specific part use vscode-nls\node. To use the browser specific part import vscode-nls\browser.

The browser specific part currently does only support a default language inline in code. There is no support yet to load a different language bundle during runtime. However the split allows to web pack the vscode-nls module.

4.1.1

• Fixes Bundled nls doesn't work

4.1.0

• support language and locale when resolving options from VSCODE_NLS_CONFIG setting.

4.0.0

• make vscode-nls webpack friendly (removal of require calls)
• narrow type for var args in localize function to string | number | boolean | null | undefined

3.0.0:

• added support to bundle the strings into a single nls.bundle(.${locale})?.json file.
• added support for VS Code language packs.

2.0.2:

• moved to TypeScript 2.1.5. Adapted to @types d.ts files instead of including typings directly into the repository.

2.0.1:

• based on TypeScript 2.0. Since TS changed the shape of the d.ts files for 2.0.x a major version number got introduce to not break existing clients using TypeScript 1.8.x.

LICENSE

MIT

vscode-nls's Issues

Add documentation about localization inside `package.json`

Missing usage document

I try to translate my extension.

Found this package, then follow the example

try and try again. but it didn't work.

Is there an easier way to define i18n?

Missing Document:

Q: What it gulp doing?

A: no answer

Q: When should I run gulp task? Is it automatic?

A: no answer

Q: What should I write in package.nls.json

A: no answer

Q: What's the relationship between package.nls.json and i18n/{lang}/package.i18n.json

A: no answer

Q: Why localize receive tow argument (key: string, message: string, ...args: any[]): string;?

...

Message bundle format info

Please add some info to the README on the message bundle format and the naming conventions used for the message bundle files.

Fallback to EN translations

Case: Extension is providing a translation file (i.e. package.nls.ja.json) but the values of the json are empty strings.
Issue: Message shows the key, not the value.
Solution: Fallback to EN translations instead of displaying the key.

@dbaeumer Are we interested in the proposed solution? Will you be accepting a PR for this?

Support locale and language when initializing from VSCODE_NLS_CONFIG

Use message: string[] and keys: string[] for structured bundles

Use fs.readFile instead of require

Today vscode-nls uses require to read JSON files, e.g. require(path.join(folder, 'nls.metadata.json')). Constructs like this prevent this module from being webpack-able and we should avoid them, e.g. by using readFile and JSON.parse

Catched an error in \lib\main.js at resolveLanguage(file) due to lack of main.nls.en.json

The error in C:\Program Files\Microsoft VS Code\resources\app\extensions\git\node_modules\vscode-nls\lib\main.js

Context:
file = "c:\Program Files\Microsoft VS Code\resources\app\extensions\git\out\main"
locale = "en"
candidate = ".nls.en.json"
_isPseude = false

The error has been threw by
if (fs.existsSync(file + candidate)) {
because there are no file main.nls.en.json in c:\Program Files\Microsoft VS Code\resources\app\extensions\git\out\

Seems this is linked with comment from [vscode/src/main.js] in getNLSConfiguration() (https://github.com/Microsoft/vscode/blob/962cd502224f7750cbf16bc676367ebab6ab35bc/src/main.js)

// Check if we have an English locale. If so fall to default since that is our
// English translation (we don't ship *.nls.en.json files)

While running in target web, I get Error: Cannot find module 'fs'

I keep getting this error when I try to import the vscode-jsonlanguage service in my webpack for target web using a umd-compat-loader.

Error: Cannot find module 'fs'
    at webpackMissingModule (main.js:8:1)
    at Object.<anonymous> (main.js:8:1)
    at ./node_modules/dependencyPackage/node_modules/vscode-json-languageservice/node_modules/vscode-nls/lib/main.js (main.js:499:1)
    at __webpack_require__ (bootstrap:789:1)
    at fn (bootstrap:100:1)
    at ./node_modules/dependencyPackagenode_modules/vscode-json-languageservice/lib/esm/parser/jsonParser.js (jsonParser.js:1:1)
    at __webpack_require__ (bootstrap:789:1)
    at fn (bootstrap:100:1)
    at ./node_modules/dependencyPackage/node_modules/vscode-json-languageservice/lib/esm/services/jsonCompletion.js (jsonCompletion.js:1:1)
    at __webpack_require__ (bootstrap:789:1)

I understand that this error occurs because I'm trying to import this for target web. But I need to use it for my web application and I'm not able to get around this issue. Also, in my use case, I won't be using the filesystem at all for interacting with the data.

Is it possible to add support for web target builds? If not, please suggest a workaround that I can try.

I've already tried fs empty in webpack.config.js

  node: {
    fs: 'empty'
  },
  externals: {
    "fs": "fs"
  }

and also I've tried adding browsr.fs: false to my package.json file.

  "browser": {
    "fs": false
  },

None of these workarounds solved the issue.

Support {key:value} structured json files

Such as

// data.nls.json
{
    "msg.hello": "Hello World"
}

Having keys and messages quickly gets messy when there are a lot of keys

Regression when bundling this library

v5.1.0 had a regression when bundling using webpack:

 WARNING in ./node_modules/vscode-nls/lib/browser/main.js 26:14-44
  Module not found: Error: Can't resolve 'vscode-nls-web-data' in '/<project-path>/node_modules/vscode-nls/lib/browser'

regressed by #42

Can't write corrupted.info file

For the details see: microsoft/vscode#86140

@Tyriar can you please check whether the directory the nls library wants to write that file exists ?

Failed to load message bundle. See console for details.

I am calling

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

in my extension.ts

and then, in other files, I am calling

let localize = nls.loadMessageBundle();

....

  const message: string = localize(
    "logoutMessage.text",
    "Successfully logged out from Machine Translation Service."
  );
  window.showInformationMessage(message);

However, when actually building my extension, I am getting "Failed to load message bundle. See console for details." I am unable to find any output in the console. What might cause this message?

extension i18n problem

I've read this issue, but still can't manage to make i18n work (source code).

I'm making vsix file with gulp package command, log is clear, also I can see localization files inside vsix file. Then I'm installing vsix bundle locally, but it doesn't change anything: localize call returns second argument, instead of key's value, specified in json.

Any ideas what I am missing?

Module not found: Can't resolve 'vscode-nls-web-data'

I keep seeing this warning when I run my Create-React-App application.
./node_modules/yaml-language-server/node_modules/vscode-json-languageservice/node_modules/vscode-nls/lib/browser/main.js
Module not found: Can't resolve 'vscode-nls-web-data' in '/<localPath>/node_modules/yaml-language-server/node_modules/vscode-json-languageservice/node_modules/vscode-nls/lib/browser'

When my application is running in the browser, I see this error logged in the browser console.

Loading vscode-nls-web-data failed. Are you running this outside of VS Code? If so, you may need to intercept the import call with your bundled NLS data.

It's not directly affecting my code but I would like to know how to fix this?

Currently, the only workaround that works for me is if I just ignore this module in webpack as follows.

const { IgnorePlugin } = require('webpack')
....
....
config.plugins.push(new IgnorePlugin({
  resourceRegExp: /vscode-nls-web-data/,
}))

But, Ignoring modules should never be the solution.
I would like to understand why this compile time warning and the browser error occurs and what can we do to fix this.

Make locale tag resolution lower case based

For all the details see microsoft/vscode#4520

localize calls cache the locale

I'm trying to use the library inside of a debug-adapter for Visual Studio, which doesn't set VSCODE_NLS_CONFIG.

From the experiments I've run it seems that localize the result of nls.loadMessageBundle(); is caching the locale when the function is called, and that if I change the locale with nls.config({ locale: 'de-DE' }) after a call to nls.loadMessageBundle() is made, the localize function is stuck on the initial locale, and not the one I configured with nls.config (A new call to nls.loadMessageBundle() returns localize with the new locale, but the already created localize functions all use the old locale).

Is there any way for me to make all the localize functions automatically change to the new locale when nls.config is called?

@dbaeumer

Link to extraction tools in README.md is broken

README.md mentions

The tools is available here.

The link is broken

Incooperate feedback regarding name

Rename cache to cacheLanguageResolution. New default will be true
Rename load to loadMessageBundle()

The default branch has been renamed from 'master' to 'main'

⚠️ Call to Action ⚠️

If you have a clone of this repository locally, you'll need to run the following commands to catch-up with the rename

git branch -m master main
git fetch origin
git branch -u origin/main main

Nls: align `config` and `loadMessageBundle` calls

From @joaomoreno on February 24, 2016 10:44

Testing #3156

When using vscode-nls, I have to call nls.config() in one file and loadMessageBundle in all the others. Couldn't we align this such that I don't need to track whether I have called nls.config() in one of my files at all?

Eg: just calling nls.config() in all files would fix it for me.

Copied from original issue: microsoft/vscode#3397

bundleMetadataFiles on windows, uses backslashes in module names

• Clone https://github.com/microsoft/vscode-chrome-debug-core
• Run gulp transifex-push-test
• See entries like <file original="out/src\errors"

When I pull from Transifex on a mac, I get files with backslashes in their names, because they are not interpreted as directory separators

unnecessary .travis.yml in npm module

suggest to remove .travis.yml in npm module

Centralize localization strings

Currently vscode-nls library is provided for VSC extension localization. But according to current design 1> the localized strings for each languages under i18n are in separated files as a mirror of source code directory and file levels. 2> the English version string is passed to localize() function as second parameter. For microsoft/vscode#1, can you provide a way to make all the localized strings in a single file for better and clearer checking. For microsoft/vscode#2, with all the English version strings embedded in code, It would be hard to track all the Eng strings, how can I make it in a single file and reference from this file?

The module should read VSCODE_NLS_CONFIG if no config is provided.

Write some documentation

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.

Add support to to pass a string to config.

Bundled nls doesn't work

vscode-nls version 4.0.0.

Repro:
In a 3rd party extension:

1. Build produces nls.bundle.*.json files in the out folder
2. Extension code uses const localize = nls.loadMessageBundle() where nls comes from import * as nls from 'vscode-nls';
loadMessageBundle calls loadNlsBundle() which hits this code:

    ...
    if (!result) {
        // No language pack found, but core is running in language pack mode
        // Don't try to use old in the box bundles since the might be stale
        // Fall right back to the default bundle.
        if (options.languagePackSupport) {
            return loadDefaultNlsBundle(bundlePath);
        }

4. Default nls bundle is loaded always even when language-specific bundles exist .

Workaround
There is no way options.languagePackSupport can be configured via nls.config().
The only ugly workaround is to change process.env.VSCODE_NLS_CONFIG and set _languagePackSupport to false before loading the vscode-nls module.

Impact:
3rd party extensions cannot use nls bundles.