VSCode 插件开发实战（十五）：如何支持多语言

🕗 发布于 2024-12-29 06:05 vscode ide 编辑器

前言

在软件开发中，多语言支持（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 库要求语言包文件的格式与之前有所不同：