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 foundreturn 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 VSCodeconst 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 类型定义和第三方库来处理复杂的翻译需求。掌握这些技术，您不仅能提高插件的用户体验，还能扩大其用户群体，推动插件在国际化市场上的应用。