Localization as part of the API

[isidorn]

This iteration we are introducing a new API that is designed to be used by extensions to localize strings. This replaces the previous vscode-nls & vscode-nls-dev modules that were used for localization in the past. Those will continue to work but will not receive any more features. The new API & tooling around it is designed to be familiar but also easier to use and more flexible. Additionally, including it as part of the API enables us to provide support for localizing your extensions for both VS Code for the desktop and VS Code for the web.

Localization for VS Code extensions has 4 important parts:

The new vscode.l10n API

declare module 'vscode' {
	export namespace l10n {
		/**
		 * A string that can be pulled out of a localization bundle if it exists.
		 */
		export function t(message: string, ...args: any[]): string;
		/**
		 * A string that can be pulled out of a localization bundle if it exists.
		 */
		export function t(options: { message: string; args?: any[]; comment: string[] }): string;
		/**
		 * The bundle of localized strings that have been loaded for the extension.
		 */
		export const bundle: { [key: string]: string };
		/**
		 * The URI of the localization bundle that has been loaded for the extension.
		 */
		export const uri: Uri | undefined;
	}
}

The vscode.l10n Proposed API is a new namespace that is available. It provides a single function t that can be used to declare that a string should be localized. The function can be called with a string or an object with a message property. The function will return the localized string if it exists, otherwise it will return the original string. The function also supports arguments that can be used to format the string and comments that can be used to provide context for translators.

A simple example of using the new API:

import { l10n } from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const message = l10n.t('Hello in {0}!', vscode.env.language);
  vscode.window.showInformationMessage(message);
}

In this example, the string Hello in {0}! will be localized if a localization bundle exists for the current language. The {0} will be replaced with the current language (en by default, or fr for French, pt-br for Brazilian Portuguese, etc). If no localization bundle exists, the string will be returned as-is and formatted with the arguments. You may be wondering where these localization bundles come from. I'll cover that in the next section.

The vscode.10n API also provides access to the bundle of localized strings or the URI to the bundle of strings. This is intended to be used in subprocess scenarios which I will cover later.

IMPORTANT

When you use this API, you also need to explicitly declare where the localization bundles are located. This is done by adding a l10n property in your package.json like so:

{
  "main": "./out/extension.js",
  "l10n": "./l10n"
}

The l10n property should be a relative path to the folder that contains the localization bundles.

The @vscode/l10n-dev module

The @vscode/l10n-dev module is a new module that is used to generate the localization bundles. You can either use it as a command line tool or as a library. Both are used to generate the localization bundles by scanning for vscode.l10n.t(..) calls from the source code provided.

Here's a simple example of using the command line tool:

npx @vscode/l10n-dev ./src --out ./l10n

This will place a bundle.l10n.json file in the ./l10n folder. From there you can make a bundle.l10n.LOCALE.json file for each locale you want to support. For example, let's say that generates the following bundle.l10n.json file:

{
  "Hello": "Hello",
  "Hello {0}": "Hello {0}",
  "Hello {0}/This is a comment": {
    "message": "Hello {0}",
    "comment": ["This is a comment"]
  }
}

If you wanted to support French, you would make this:

{
  "Hello": "Bonjour",
  "Hello {0}": "Bonjour {0}",
  "Hello {0}/This is a comment": "Bonjour {0}"
}

NOTE: You don't need the comments in the localized bundles since the comments are only useful for translators translating the original bundle.

The @vscode/l10n-dev module can also be used to generate XLF files. The VS Code team generates XLF files that we then give to translators at Microsoft. The translators then give us back the translated XLF files. We then use the @vscode/l10n-dev module to generate the localized bundles from the translated XLF files. At some point, we plan on writing a blog post that goes into more detail about our localization process as a whole.

The @vscode/l10n module

Since the vscode.l10n API is only available in the extension host, it cannot be used in subprocesses. For this reason, we have created a new module that can be used in subprocesses to load the localization bundles. The module is called @vscode/l10n and it can be used like so:

import { l10n } from '@vscode/l10n';

// Load the translations for the current locale
l10n.config({
    uri: process.env.BUNDLE_URI_FROM_EXTENSION
});

// returns the translated string or the original string if no translation is available
l10n.t('Hello World');

The idea is that your extension-side code who is responsible for spinning up the subprocesses will use the vscode.l10n.contents or vscode.l10n.uri APIs to pass the bundle or the URI of the bundle to the subprocesses. The subprocesses can then use the @vscode/l10n module to load the bundle and use the t function to translate strings. The t function used by the @vscode/l10n module will also be picked up in the @vscode/l10n-dev module so that the strings can be extracted and localized using one process.

The package.nls.json file

Nothing has changed with respect to the package.nls.json file. It is still used to declare the default strings that should be localized and should be next to the package.json. You still can have package.nls.LOCALE.json (where LOCALE is something like de or zh-cn) and the strings declared in that file will be picked up first if the user has set VS Code to that locale. A small example:

Your package.json:

{
  "name": "my-extension",
  "version": "0.0.1",
  "main": "./out/extension.js",
  "l10n": "./l10n",
  //...
  "contributes": {
    "commands": [
      {
        "command": "my-extension.helloWorld",
        // The key is surrounded by % characters
        "title": "%my-extension.helloWorld.title%"
      }
    ]
  }
}

Your package.nls.json:

{
  // That same key from the package.json
  "my-extension.helloWorld.title": "Hello World"
}

Your package.nls.de.json:

{
  // That same key from the package.json
  "my-extension.helloWorld.title": "Hallo Welt"
}

Summary

There's certainly a lot here to digest, but hopefully this gives you an idea of the direction we're trying to take with localization in VS Code extensions.

If you're interested in a full example, we have a sample that you can check out here.

If you have questions or feedback, please let us know in the following places:

• The API proposal of vscode.l10n
• The vscode-l10n repo (home of the @vscode/l10n-dev and @vscode/l10n modules)

Try it out and let us know what you think!

fyi @TylerLeonhardt

[bwateratmsft]

@isidorn one discussion that @philliphoff and I had yesterday relates to strings that are identical in, say, English, but not in other languages. These could be differentiated by using the comment feature for a message, because the comment is used as part of the key in the bundle.

However, suppose you are converting an existing extension that has been using vscode-nls. It would not be scalable to identify every reused string on a manual basis. Can the @vscode/l10n-dev package have a feature to help find places where the same string is reused, so the authors can decide if a comment needs to be added to ensure uniqueness in the bundles?

[TylerLeonhardt]

Can the @vscode/l10n-dev package have a feature to help find places where the same string is reused, so the authors can decide if a comment needs to be added to ensure uniqueness in the bundles?

Can you open an issue over in https://github.com/Microsoft/vscode-l10n

[bwateratmsft]

Done! microsoft/vscode-l10n#28

[mauri]

@isidorn could you fix the typos around calling the api vscode.10n instead of vscode.l10n? thanks