Here's a simple example of using the command line tool:
npx @vscode/l10n-dev export --outDir ./l10n ./src
This will search all TypeScript files in ./src and place a bundle.l10n.json file in the ./l10n folder with all the strings you want to be localized. From there you can make a bundle.l10n.LOCALE.json file for each locale you want to support. For example, let's say that the command above 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 create this in a bundle.l10n.fr.json file:
{ "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.
Warning
Make sure your package.json has an l10n field that points to where you are storing these bundles. For example:
{ "main": "./out/extension.js", "l10n": "./l10n"}
Psuedo-Localization
If you don't speak another language but want to test out localization changes, you can use the Pseudolocalization generator built in to the @vscode/l10n-dev package. Give it a try:
This will create a package.nls.qps-ploc.json file and a bundle.l10n.qps-ploc.json file. If you install the Pseudo Language Language Pack, you'll be able to set VS Code to this locale which will pull strings for this extension out of the respective qps-ploc files. The qps-ploc is the language code for Pseudolocalization used by VS Code.
This will create a package.nls.<language>.json file and a bundle.l10n.<language>.json file for each language that VS Code supports (you can choose the languages using the -l flag).
Advanced usage
Generating an XLIFF file
The VS Code team generates XLIFF (.xlf) files that we then give to translators at Microsoft. The translators then give us back the translated XLIFF files. We then use the @vscode/l10n-dev module to generate the localized bundles from the translated XLIFF files. We plan on writing a blog post that goes into more detail about our localization process as a whole.
If you find yourself needing to generate an XLIFF file, you can use the generate-xlf command. This command will generate an XLIFF file from the the strings in your package.nls.json and your newly extracted strings (bundle.l10n.json).
-o is the alias for --outFile. You can optionally specify a --language or -l to specify the language of the XLIFF file. en is the default.
XLIFF has a wide range of tools out there. As we learn about successful workflows, we'll add them here.
Importing an XLIFF file
If you receive your translations from your translators in the form of an XLIFF file, you can use the import-xlf command to import the translations into *.l10n.<language>.json files.
You can optionally specify an --outDir or -o to specify where the extracted strings should be written to. Current working directory is the default.
This command will then place a bundle.l10n.<language>.json and a package.nls.<language>.json file in the current working directory for whatever language that XLIFF file targets.
As a library
npm install --save-dev @vscode/l10n-dev
or yarn equivalent.
import * as path from 'path';import { readFileSync } from 'fs';import { getL10nJson, getL10nXlf, getL10nFilesFromXlf, l10nJsonFormat } from '@vscode/l10n-dev';// Get the computed l10n json from a set of filesconst result = getL10nJson([readFileSync('extension.ts', 'utf8')]);// Get the computed xlf from l10n JSON dataconst map = new Map<string, l10nJsonFormat>();map.set('package', readFileSync(path.resolve('package.l10n.json')));map.set('bundle', result);