国际化

i18n 系统概述

Markdown Here 扩展根据不同的浏览器平台采用不同的国际化方法：

对于 Chrome 和基于 Chromium 的浏览器，它使用标准的 Chrome 扩展 i18n API
对于 Firefox 和 Thunderbird，它将源文件转换为 Mozilla 特定的本地化格式

该系统从一组定义所有用户可见字符串的源 JSON 文件开始，然后在构建过程中根据需要对其进行转换。

来源：utils/i18n.js1-157 src/_locales/en/messages.json1-361

消息存储格式

所有本地化字符串最初都以 JSON 格式存储，遵循 Chrome 的国际化约定。每种语言都在 src/_locales/ 下有自己的目录。

源 JSON 结构

JSON 结构遵循以下模式：

{
  "message_key": {
    "message": "Actual message text",
    "description": "Explanation to help translators",
    "inMozDTD": true/false (optional)
  },
  ...
}

message_key: 字符串的唯一标识符
message: 实际的翻译文本
description: 供翻译人员参考的上下文
inMozDTD: 当为 true 时，表示该字符串应包含在 Mozilla DTD 文件中

英语 (en) 是参考语言，所有其他语言文件必须包含与英语文件相同的键。

来源：src/_locales/en/messages.json1-361 src/_locales/ja/messages.json1-355 src/_locales/fr/messages.json1-355 src/_locales/es/messages.json1-355 src/_locales/pt_BR/messages.json1-355

构建流程

在构建过程中，i18n.js 工具脚本会将源 JSON 文件转换为平台特定格式。

来源：utils/i18n.js36-142

字符串处理

构建过程执行多项字符串转换：

确保所有语言文件都具有完整的键集（如有必要，使用英语作为回退）
处理特殊字符序列（例如，$$ 变为 $）
根据需要为属性文件转义字符
分离 DTD 文件的字符串（带有 inMozDTD: true 的字符串）
使用本地化的应用程序名称和描述更新 Mozilla 的 install.rdf 清单

来源：utils/i18n.js96-142

运行时本地化

在运行时，本地化字符串的访问方式因浏览器平台而异：

基于 Chrome 的浏览器

Chrome 扩展使用标准的 Chrome i18n API

Firefox/Thunderbird

Firefox/Thunderbird 扩展从生成的属性和 DTD 文件加载字符串

JavaScript 代码使用字符串包访问属性文件中的字符串
XUL/HTML 文件直接在标记中访问 DTD 实体

支持的语言

目前，Markdown Here 支持以下语言：

语言	区域码	文件
英语	en	messages.json, strings.properties, strings.dtd
日语	ja	messages.json, strings.properties, strings.dtd
法语	fr	messages.json, strings.properties, strings.dtd
西班牙语	es	messages.json, strings.properties, strings.dtd
巴西葡萄牙语	pt_BR	messages.json, strings.properties, strings.dtd

来源：src/_locales/en/messages.json1-361 src/_locales/ja/messages.json1-355 src/_locales/fr/messages.json1-355 src/_locales/es/messages.json1-355 src/_locales/pt_BR/messages.json1-355

区域设置解析和映射

Chrome 区域设置代码和 Mozilla 区域设置代码之间存在映射过程。这是必要的，因为这两个平台使用不同的区域设置标识标准。

区域设置映射在 chrome.manifest 文件中定义，并在构建过程中由 i18n.js 脚本处理。

来源：utils/i18n.js145-157

特殊注意事项

美元符号转义

在 Chrome i18n 字符串中，美元符号 ($) 用于占位符，因此要表示一个字面美元符号，源 JSON 中必须使用 $$。构建过程会处理此转换。

"message": "This costs $$10" --> Rendered as "This costs $10"

来源：utils/i18n.js117-122

Mozilla DTD 选择

只有标记为 inMozDTD: true 的字符串才包含在生成的 DTD 文件中。这些通常是直接在 XUL/HTML 标记中使用的字符串，而不是通过 JavaScript 加载的。

来源：src/_locales/en/messages.json11-15 utils/i18n.js128-130

新增翻译

若要为 Markdown Here 添加新语言：

在 src/_locales/ 中创建新目录，并使用适当的语言代码
从英语区域设置中复制 messages.json 并翻译所有消息值
在 chrome.manifest 中添加条目，将 Chrome 区域设置代码映射到 Mozilla 区域设置代码
运行构建脚本以生成必要的平台特定文件

构建过程将处理为 Firefox/Thunderbird 创建所有必要文件。

贡献流程

Markdown Here 积极寻求社区的翻译贡献。鼓励贡献者帮助将此扩展翻译成新语言，如选项页面所述：

"Help make Markdown Here available in your language. Translations are welcome."

来源：src/_locales/en/messages.json319-321

未来增强

i18n 系统的一些可改进领域：

跨平台消息占位符/变量支持
更自动化的翻译验证
支持 RTL（从右到左）语言
无需重新加载扩展即可动态切换语言

技术实现细节

浏览器差异

不同浏览器对 i18n 的支持程度各不相同：

Chrome 扩展具有内置的 i18n API
Firefox/Thunderbird 需要自定义区域设置文件和字符串包
其他浏览器可能有不同的机制

构建系统通过为每个平台生成相应的文件来处理这些差异。

同步机制

i18n.js 脚本通过以下方式确保所有翻译文件包含完整的一组消息：

将英语源文件作为参考
对于每种语言，将其翻译与英语源文件合并
对任何缺失的翻译使用英语回退
对键进行排序以在更新文件时最小化差异搅动

来源：utils/i18n.js93-104

这种方法确保可以将新字符串添加到英语源文件中，而不会立即破坏其他语言文件。任何未翻译的字符串都将回退到英语，直到提供翻译。

国际化