i18n

The complete extension includes VS Code extension, OpenSumi extension, and package.json contribution points. For different environments and extension functions, the internationalization implementation is compatible with the VS Code extension and also has a certain degree of Scalability.

VS Code

OpenSumi is compatible with some language pack extensions officially provided by VS Code (it is recommended to use OpenSumi versions above 2.23.6), such as:

Currently only supports zh-cn and en-us two language switching capabilities, if you have further needs, you can submit adaptation requirements at issues .

The VS Code extension abandoned the original i18n scheme after version 1.74. It is recommended to use the new l10n in the extension as an alternative. If you encounter text that cannot be normally internationalized, you can check the extension version and consider using An older extension version.

At present, OpenSumi does not support localization extensions implemented through vscode.l10n. If you encounter related problems, you can leave a message at #2341 or + 1. We will further speed up the adaptation process.

Declaration in PackageJSON

The extension package.json supports some purely static contribution points such as Menu and Command. The text in these contribution points can use the placeholder of %{section}% to declare the fields of the internationalized text, such as registration one command:

{
  "contributes": {
    "commands": [
      {
        "command": "Hello OpenSumi",
        "title": "%test-extension-hello-command%"
      }
    ]
  },
}

Add a new file named package.nls.json in the extension as the default English language package

{
  "test-extension-hello-command": "Test i18n for command"
}

For Chinese, it needs to be written in package.nls.zh-cn.json, such as:

{
  "test-extension-hello-command": "Test command internationalization"
}

Similarly, any contribution point that can display copywriting in the IDE interface contributed by the extension can register the language pack in this way, for example, it can be used in configurations like this:

{
  ...
  "configuration": {
    "title": "%test-extension-config-title%",
    "properties": {
      "my-extension.enable-auto-bugfix-feature": {
        "type": "boolean",
        "default": false,
        "description": "%test-extension-config.config.enable-feature%"
      }
    }
  }
  ...
}

The extension contribution point will register a configuration item to the framework settings page, which is also declared in package.nls.json and package.nls.zh-cn.json

{
  "test-extension-config-title": "Test Extension Configuration",
  "test-extension-config.config.enable-feature": "Test enable feature"
}

The effect is as follows:

configurations

Node layer uses

Refer to VS Code i18n Sample, you need to follow the structure of i18n/{language} in the internationalization language pack written in the extension. If your extension source code file src/utils.ts needs internationalization support, you should write the language copy in i18n/out/utils.i18n.json, and write OpenSumi extension Node code in the same way.

The above examples are applicable to pure VS Code extensions built with gulpfile.js, some new version extensions may not be applicable.

For extension projects initialized with OpenSumi CLI, the latest version of vscode-nls needs to be installed in the extension before use. The sample code is as follows:

// extension.ts or extend/node/index.ts
import * as nls from 'vscode-nls';
import * as vscode from 'vscode';

const localize = nls.config({
  messageFormat: nls.MessageFormat.bundle,
  bundleFormat: nls.BundleFormat.standalone
})();

function activate() {
  vscode.window.shoeInfomationMessage(localize('i18n.key', 'defaulMessage'));
}

// others
import * as nls from 'vscode-nls';

const localize = nls.loadMessageBundle();

//...

Different from the VS Code, the parameters of nls.config have some differences in writing:

// when using gulp + tsc
const localize = nls.config({ messageFormat: nls.MessageFormat.file });

// when using OpenSumi CLI / webpack
const localize = nls.config({
  messageFormat: nls.MessageFormat.bundle,
  bundleFormat: nls.BundleFormat.standalone
})();

Different parameters correspond to how the vscode-nls module will load the language pack file at runtime.

  • If it is a pure VS Code extension, use gulp + tsc to build the extension, then the language pack of the corresponding file will be loaded through the i18n directory structure at runtime, and only nls.metadata.json and nls.metadata will be generated during construction .header.json is used to record the corresponding language file.
  • If you use the OpenSumi extension Node side, or use the VS Code extension packaged by Webpack to compress the extension into a single file, the runtime will try to load the nls.bundle.{language}.json file in the i18n directory.

At the same time, according to the VS Code extension example, if the language directory corresponding to i18n contains package.nls.json (such as i18n/zh-cn/package.nls.json), when using the sumi compile/watch command It will also be extracted into the extension root directory and renamed to package.nls.{language}.json.

Whether it is a VS Code extension or an OpenSumi extension, when running sumi compile or sumi watch, the corresponding language will be extracted to the out/ directory at the same time.

WEBPACK Hash: 1da8c87af3944336632a
Version: webpack 4.44.1
Time: 1197ms
Built at: 2020-08-10 20:52:32
                   Asset       Size  Chunks             Chunk Names
                index.js   7.86 KiB       0  [emitted]  index
     nls.bundle.jpn.json   24 bytes          [emitted]  // Japanese language pack
         nls.bundle.json   52 bytes          [emitted]  // Default language pack
   nls.bundle.zh-cn.json   37 bytes          [emitted]  // Chinese language pack
nls.metadata.header.json  149 bytes          [emitted]  // metadata
       nls.metadata.json  118 bytes          [emitted]  // metadata
WEBPACK Compiled successfully in 1.2s!

Browser usage

In the Browse, text can also be declared in package.nls.json, but it needs to be imported from the sumi-browser module when using the localize method. The first parameter represents the copywriting id, which is declared in package. The field name in nls.json, the second parameter is the default value when the corresponding language pack copy cannot be found.

import { localize } from 'sumi-browser';

export const MyPanel = () => {
  return <div>{localize('test-extension-view-title', 'Test Title')}</div>;
};

The definition in package.nls.json is as follows:

{
  "test-extension-view-title": "Test Title"
}

Reference example

OpenSumi Extension Sample - i18n