VSCode 插件开发实战（十五）：如何支持多语言
前言
在软件开发中，多语言支持（i18n）是一个非常重要的功能。无论是桌面应用、移动应用，还是浏览器插件，都需要考虑如何支持不同国家和地区的用户，软件应用的多语言支持（i18n）已经成为提升用户体验的关键因素之一。
那么如何为您的自定义 VSCode 插件添加多语言支持，以便更好地服务来自不同语言背景的开发者？本教程将详细介绍如何通过简单而高效的方法，为您的 VSCode 插件实现多语言支持，从而提升其国际化能力。
添加多语言支持
1. 创建语言包文件
在你的插件项目中，创建一个 i18n 目录，用于存放不同语言的翻译文件。每种语言会对应一个单独的 JSON 文件，比如 en.json（英文）和 zh-cn.json（中文）。
en.json
{
"helloWorld": "Hello, World!",
"greeting": "Welcome to our VSCode extension!"
}
zh-cn.json
{
"helloWorld": "你好，世界！",
"greeting": "欢迎使用我们的 VSCode 插件！"
}
完整示例
以下是一个完整的插件目录结构示例：
my-vscode-extension
├── .vscode
│ ├── tasks.json
│ └── launch.json
├── .gitignore
├── README.md
├── package.json
├── src
│ ├── extension.ts
│ └── i18n
│ ├── en.json
│ └── zh-cn.json
├── tsconfig.json
└── vsc-extension-quickstart.md
2. 加载语言包
接下来，我们需要在插件代码中加载这些语言包。可以在 extension.js 或 extension.ts 中实现这一功能。
extension.ts
import * as vscode from 'vscode';
import * as path from 'path';
import * as fs from 'fs';
function loadMessageBundle(locale: string) {
const filePath = path.join(__dirname, 'i18n', `${locale}.json`);
if (fs.existsSync(filePath)) {
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
} else {
// Default to English if locale file is not found
return JSON.parse(fs.readFileSync(path.join(__dirname, 'i18n', 'en.json'), 'utf8'));
}
}
export function activate(context: vscode.ExtensionContext) {
const locale = vscode.env.language; // Get the current language setting of VSCode
const messages = loadMessageBundle(locale);
let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
vscode.window.showInformationMessage(messages['helloWorld']);
});
context.subscriptions.push(disposable);
}
export function deactivate() {}
3. 更新 package.json
最后，我们需要更新 package.json 文件，声明插件的语言包配置。
{
"contributes": {
"localizations": [
{
"languageId": "en",
"languageName": "English",
"translations": [
{
"id": "en",
"path": "./i18n/en.json"
}
]
},
{
"languageId": "zh-cn",
"languageName": "Chinese (Simplified)",
"translations": [
{
"id": "zh-cn",
"path": "./i18n/zh-cn.json"
}
]
}
]
}
}
进阶操作
动态切换语言
有时候，用户可能希望在不重启 VSCode 的情况下切换语言。我们可以借助 VSCode API 实现这一功能。
修改 extension.ts
首先，我们需要修改 extension.ts 文件，以支持动态加载语言包。
import * as vscode from 'vscode';
import * as path from 'path';
import * as fs from 'fs';
let currentLocale: string = vscode.env.language;
let messages: { [key: string]: string };
function loadMessageBundle(locale: string) {
const filePath = path.join(__dirname, 'i18n', `${locale}.json`);
if (fs.existsSync(filePath)) {
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
} else {
return JSON.parse(fs.readFileSync(path.join(__dirname, 'i18n', 'en.json'), 'utf8'));
}
}
function refreshMessages() {
messages = loadMessageBundle(currentLocale);
}
export function activate(context: vscode.ExtensionContext) {
refreshMessages();
let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
vscode.window.showInformationMessage(messages['helloWorld']);
});
let changeLocaleCommand = vscode.commands.registerCommand('extension.changeLocale', async () => {
const picked = await vscode.window.showQuickPick(['en', 'zh-cn'], {
placeHolder: 'Select a language'
});
if (picked) {
currentLocale = picked;
refreshMessages();
vscode.window.showInformationMessage(messages['greeting']);
}
});
context.subscriptions.push(disposable, changeLocaleCommand);
}
export function deactivate() {}
更新 package.json
为了让用户能够通过命令面板切换语言，我们需要在 package.json 中添加相应的命令配置。
{
"contributes": {
"commands": [
{
"command": "extension.helloWorld",
"title": "Hello World"
},
{
"command": "extension.changeLocale",
"title": "Change Language"
}
],
"localizations": [
{
"languageId": "en",
"languageName": "English",
"translations": [
{
"id": "en",
"path": "./i18n/en.json"
}
]
},
{
"languageId": "zh-cn",
"languageName": "Chinese (Simplified)",
"translations": [
{
"id": "zh-cn",
"path": "./i18n/zh-cn.json"
}
]
}
]
}
}
使用 TypeScript 类型定义
为了编写更健壮的代码，我们可以为语言包定义一个类型，并在加载语言包时进行类型检查。
定义类型
interface Messages {
helloWorld: string;
greeting: string;
}
修改 loadMessageBundle 函数
function loadMessageBundle(locale: string): Messages {
const filePath = path.join(__dirname, 'i18n', `${locale}.json`);
if (fs.existsSync(filePath)) {
return JSON.parse(fs.readFileSync(filePath, 'utf8')) as Messages;
} else {
return JSON.parse(fs.readFileSync(path.join(__dirname, 'i18n', 'en.json'), 'utf8')) as Messages;
}
}
这样，我们在使用 messages 对象时，TypeScript 会帮助我们进行类型检查，确保代码的可靠性。
处理复杂的翻译需求
在实际应用中，翻译内容可能不仅仅是简单的字符串，还会涉及变量和占位符。我们可以使用较为成熟的 i18n 库来处理这些复杂的翻译需求。例如，使用 i18n 或 i18next 库。
使用 i18n
首先，安装 i18n 库：
npm install i18n
配置 i18n
import * as i18n from 'i18n';
import * as path from 'path';
i18n.configure({
locales: ['en', 'zh-cn'],
directory: path.join(__dirname, 'i18n'),
defaultLocale: 'en',
extension: '.json',
register: global
});
function setLocale(locale: string) {
i18n.setLocale(locale);
}
export function activate(context: vscode.ExtensionContext) {
setLocale(vscode.env.language);
let disposable = vscode.commands.registerCommand('extension.helloWorld', () => {
vscode.window.showInformationMessage(__('helloWorld'));
});
let changeLocaleCommand = vscode.commands.registerCommand('extension.changeLocale', async () => {
const picked = await vscode.window.showQuickPick(['en', 'zh-cn'], {
placeHolder: 'Select a language'
});
if (picked) {
setLocale(picked);
vscode.window.showInformationMessage(__('greeting'));
}
});
context.subscriptions.push(disposable, changeLocaleCommand);
}
export function deactivate() {}
修改语言包格式
i18n 库要求语言包文件的格式与之前有所不同：
en.json
{
"helloWorld": "Hello, World!",
"greeting": "Welcome to our VSCode extension!"
}
zh-cn.json
{
"helloWorld": "你好，世界！",
"greeting": "欢迎使用我们的 VSCode 插件！"
}
总结
通过本文的详细步骤，我们深入探讨了如何为 VSCode 自定义插件添加多语言支持。我们从创建简单的语言文件开始，逐步实现了动态切换语言的功能，并结合 TypeScript 类型定义和第三方库来处理复杂的翻译需求。掌握这些技术，您不仅能提高插件的用户体验，还能扩大其用户群体，推动插件在国际化市场上的应用。