国际化

目的与范围

本文档描述了 Shadowsocks Windows 的国际化系统。该系统使应用程序能够根据用户的系统区域设置显示多种语言的文本。它涵盖了翻译机制、翻译文件结构以及如何添加或修改翻译。

系统概览

Shadowsocks Windows 客户端使用一个简单而有效的国际化系统，它从 CSV 文件加载翻译并将其应用于用户界面元素。该系统自动检测用户的系统区域设置并选择合适的翻译。

来源：shadowsocks-csharp/Controller/I18N.cs11-123

翻译文件结构

翻译系统使用一个 CSV 文件（i18n.csv），其结构如下

第一行包含语言代码（例如，en、ru-RU、zh-CN）
每一行都包含一个英文的键字符串及其在其他语言中的翻译
以 # 开头的行被视为注释

以下是翻译文件中的一个示例

en	ru-RU	zh-CN	zh-TW	ja	ko	fr
系统代理	系统代理	系统代理	系统代理	系统代理	系统代理	系统代理
禁用	禁用	禁用	禁用	禁用	禁用	禁用
PAC	PAC 模式	PAC 模式	PAC 模式	PAC 模式	PAC 模式	PAC

文件应以 UTF-8 带 BOM 编码保存，以支持所有国际字符并确保其可以在 Excel 中编辑。

来源：shadowsocks-csharp/Data/i18n.csv1-155

翻译流程

来源：shadowsocks-csharp/Controller/I18N.cs21-95

实现细节

I18N 类

I18N 类是一个静态工具类，用于管理所有国际化功能。

静态构造函数：通过从 CSV 文件或嵌入式资源加载翻译来初始化翻译系统。
Init 方法：解析 CSV 数据并构建翻译字典。
GetString 方法：检索给定键的翻译。
TranslateForm/TranslateMenu 方法：递归翻译 UI 元素中的所有文本。

来源：shadowsocks-csharp/Controller/I18N.cs13-122

语言选择逻辑

系统使用以下逻辑选择合适的语言：

获取当前系统区域性（CultureInfo.CurrentCulture.Name）
在 CSV 标题中查找精确匹配项（例如，“zh-CN”）
如果未找到，尝试仅匹配语言部分（例如，“zh”）
如果仍然未找到，则回退到英语

这种方法确保用户获得其区域设置的最佳翻译。

来源：shadowsocks-csharp/Controller/I18N.cs30-60

支持的语言

默认的 i18n.csv 文件包含以下语言的翻译：

英语 (en) - 基础语言
俄语 (ru-RU)
简体中文 (zh-CN)
繁体中文 (zh-TW)
日语 (ja)
韩语 (ko)
法语 (fr)

来源：shadowsocks-csharp/Data/i18n.csv1

代码中的使用

在应用程序代码中使用翻译

对于用户界面元素

表单和菜单可以使用辅助方法自动翻译。

对于字符串翻译

单个字符串可以使用 GetString 方法进行翻译。

来源：shadowsocks-csharp/Controller/I18N.cs97-121

添加或修改翻译

添加新语言或更新现有翻译

在电子表格应用程序中打开 i18n.csv 文件
要添加新语言，请在标题行中添加一个包含相应语言代码的新列。
填写所有英文字符串的翻译。
将文件保存为 UTF-8 带 BOM 编码的 CSV 格式。
将文件放置在 Shadowsocks 可执行文件所在的目录中。

对于处理源代码的贡献者，翻译也可以在嵌入式资源文件中更新。

调试翻译

如果翻译未正确显示：

检查应用程序日志中有关当前语言的消息
- 当前语言为：[locale]
- 正在为 [locale] 使用 [language] 翻译
- 未找到 [locale] 的翻译
验证 i18n.csv 文件格式正确并以 UTF-8 带 BOM 编码。
确保键字符串与代码中的内容完全匹配（包括空格）。

与应用程序集成

国际化系统已集成到整个应用程序中。一些值得注意的例子：

用户界面元素：所有表单、对话框和菜单都在初始化时进行翻译。
错误消息：错误消息以英文定义，并在显示前进行翻译。
服务器响应：某些服务器响应包含翻译后的字符串（例如，在 PAC 服务器中）。

来源：shadowsocks-csharp/Controller/Service/PACServer.cs169-176

结论

Shadowsocks Windows 中的国际化系统旨在简单而有效。它提供了一种直接的方法，可以将应用程序翻译成多种语言，同时最大限度地减少开销。通过使用基于 CSV 的方法，它使非开发人员也能够方便地贡献翻译。

国际化