mirror of
https://github.com/microsoft/vscode-extension-samples.git
synced 2026-06-13 07:10:26 +08:00
103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# README
|
|
## This is the README for the "i18n-sample"
|
|
-------------------
|
|
|
|
This folder contains a sample VS code extension that shows how to use the
|
|
package.nls.json and the vscode-nls library for localization. For this sample,
|
|
it shows two commands: Hello and Bye in English and Japanese.
|
|
|
|
**Assumptions**
|
|
|
|
* All localization files are under the i18n folder.
|
|
* You could have created this folder by hand, or you could have used the `vscode-nls-dev` tool to extract it.
|
|
* Under the i18n folder, you have sub-folders that represent the language you want to localize. These names follow the ISO 639-3 convention.
|
|
* Under the language names folder you will create json files that mirror the structure of the source code for your extension (e.g., out/src). The json files are key:value pairs of the text that you want to localize. The naming convention is `<file_name>.i18n.json`.
|
|
* If you have a top-level package.nls.json file in your extension, you should have one for each language following the naming convention of `package.i18n.json`.
|
|
|
|
# How to run locally
|
|
|
|
Localization values are only applied when running the gulp `build` task. During normally development which uses `tsc -watch` to compile no localization post processing happends. This speeds up development time.
|
|
|
|
1. Ensure that you have `gulp-cli` installed globally using `npm install --global gulp-cli`.
|
|
1. Run `npm install` to bring in the dependencies.
|
|
1. Follow the steps at https://code.visualstudio.com/docs/extensions/publish-extension to ensure that you have installed vsce and have a publisher account.
|
|
1. Run `gulp package` to produce a .vsix file.
|
|
1. Install the .vsix file following the instructions at https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix
|
|
1. Change your locale to Japanese by invoking "Configure Language" from the Command Palette.
|
|
|
|
See the demo.gif file in this repository for a screencast.
|
|
|
|
# How to translate our extension
|
|
|
|
VS Code itself uses [Transifex](https://www.transifex.com/) to manage its translations. This might be an option for your extension as well, however none of the nls tooling provided by `vscode-nls` or `vscode-nls-dev` requires Transifex as its translation platform. So you are free to choose a different one.
|
|
|
|
# What happens behind the scenes
|
|
|
|
1. The `vscode-nls-dev` module is used to rewrite the generated JavaScript.
|
|
1. Calls of the form `localize('some_key', 'Hello')` are transformed to `localize(0, null)` where the first parameter (0, in this example) is the position of the key in your messages file.
|
|
1. The contents of the i18n folder are transformed from key:value pairs into positional arrays.
|
|
|
|
# Considerations
|
|
|
|
It is possible to use your own localization pipeline.
|
|
|
|
1. Localizations in your package.json can be done by wrapping the localized text in the form %some.key%.
|
|
|
|
```
|
|
// [Before] package.json
|
|
|
|
"contributes": {
|
|
"commands": [
|
|
{
|
|
"command": "extension.sayHello",
|
|
"title": "Hello"
|
|
}
|
|
]
|
|
|
|
// [After] package.json
|
|
|
|
"contributes": {
|
|
"commands": [
|
|
{
|
|
"command": "extension.sayHello",
|
|
"title": "%extension.sayHello.title%"
|
|
}
|
|
]
|
|
|
|
// [After] new package.nls.json
|
|
|
|
{
|
|
"extension.sayHello.title": "Hello",
|
|
}
|
|
|
|
```
|
|
|
|
Then, create the corresponding package.nls.{your_language}.json files for each language to localize.
|
|
|
|
2. It is also possible to use your own library for localizing text in your source file. You would use the value of `process.env.VSCODE_NLS_CONFIG` environment variable. At runtime, this environment variable is a JSON string that contains the locale that VS Code is run with. For instance, this is the value for Japanese: `"{"locale":"ja","availableLanguages":{"*":"ja"}}"`
|
|
|
|
```JavaScript
|
|
|
|
function localize(config) {
|
|
const messages = {
|
|
en: 'Hello',
|
|
ja: 'こんにちは'
|
|
};
|
|
return messages[config['locale']];
|
|
}
|
|
|
|
const config = JSON.parse(process.env.VSCODE_NLS_CONFIG);
|
|
localize(config);
|
|
|
|
```
|
|
|
|
# History
|
|
|
|
## 0.0.2
|
|
|
|
Hook up the vscode-nls-dev functions to gulp so that you can just run `vsce package` without manual transformations.
|
|
|
|
## 0.0.1:
|
|
|
|
Manually transform the calls to localize to illustrate explicitly what is going on.
|