特定语言环境实现

1. 本地化文件组织

Markdown Here 根据目标浏览器平台以两种不同的结构组织本地化文件。这种双重结构使扩展能够为基于 Chrome 的浏览器、Firefox 和 Thunderbird 提供适当的本地化方法支持。

1.1. 基于 Chrome 的浏览器文件

对于 Chrome 和其他基于 Chromium 的浏览器，本地化文件存储在src/_locales目录中。每种受支持的语言都有其自己的子目录，以相应的语言代码命名（例如，ko 代表韩语，ja 代表日语）。

每个本地化目录中包含：

messages.json：包含 JSON 格式的 UI 字符串
description.txt：包含用于商店列表的扩展描述

来源：src/_locales/ko/messages.json1-355 src/_locales/ja/description.txt1-24

1.2. Firefox/Thunderbird 文件

对于 Firefox 和 Thunderbird，本地化文件存储在src/firefox/chrome/locale目录中。每种语言也都有其自己的子目录，以语言代码命名。

Firefox/Thunderbird 的每个本地化目录中包含：

strings.properties：包含本地化字符串的键值对
strings.dtd：包含用于 XUL 接口的 XML 样式实体声明

来源：src/firefox/chrome/locale/ko/strings.properties1-95 src/firefox/chrome/locale/en/strings.dtd1-10 src/firefox/chrome/locale/ja/strings.dtd1-10

2. 消息格式和结构

消息格式在基于 Chrome 的浏览器和 Firefox/Thunderbird 实现之间有所不同。本节详细介绍了每种格式中消息的结构。

2.1. 基于 Chrome 的格式 (JSON)

在基于 Chrome 的浏览器中，消息以 JSON 格式存储，结构如下：

"message_id": {
  "message": "Translated text",
  "description": "Context for translators",
  "inMozDTD": boolean (optional)
}

来自韩语 messages.json 的示例

"context_menu_item": {
  "message": "마크다운 토글",
  "description": "Text shown on the context menu.",
  "inMozDTD": true
}

的inMozDTD标志表示此消息也在 Firefox/Thunderbird DTD 文件中使用。

来源：src/_locales/ko/messages.json11-15

2.2. Firefox/Thunderbird 格式

2.2.1. Properties 格式

strings.properties文件使用简单的键值对格式：

message_id=Translated text

来自韩语 strings.properties 的示例

context_menu_item=마크다운 토글

来源：src/firefox/chrome/locale/ko/strings.properties3

2.2.2. DTD 格式

strings.dtd文件使用 XML 实体声明：

<!ENTITY message_id "Translated text">

来自英语 strings.dtd 的示例

<!ENTITY context_menu_item "Markdown Toggle">

来源：src/firefox/chrome/locale/en/strings.dtd2 src/firefox/chrome/locale/ja/strings.dtd1-10

3. 消息检索过程

下图说明了本地化消息是如何检索并显示给用户的：

浏览器向扩展提供本地化信息，然后扩展使用适当的 i18n 系统从正确的本地化文件中加载消息。此过程通过 i18n 实用函数从主代码中抽象出来。

4. 本地化特殊考量

4.1. 消息中的 HTML

某些消息包含必须在翻译过程中保留的 HTML 标记。例如：

"options_page__click_toggle": {
  "message": "Right-click in the email and then click \"Markdown Toggle\". (Or click the <img src=\"images/icon16.png\"/> button on the toolbar.<span class=\"hotkey-display-wrapper\"> Or press <span class=\"hotkey-display\"><kbd>CTRL</kbd>+<kbd>ALT</kbd>+<kbd>M</kbd></span></span>)",
  "description": "A step in the basic usage instructions"
}

译者必须确保 HTML 标签保持正确平衡，并且属性得到保留。

来源：src/_locales/ko/messages.json86-88

4.2. 占位符

某些消息使用占位符，这些占位符在运行时会被动态内容替换。例如，在 TeX 数学支持中：

"options_page__tex_math_customization_5_1": {
  "message": "<code>{mathcode}</code>: The text between the <code>$$</code> symbols — i.e., the raw TeX formula; like <code>\\Delta</code>.",
  "description": "Please do not translate {mathcode} and {urlmathcode}. Note: Double dollar signs ($$) are necessary to get a single dollar sign."
}

译者被指示不要翻译诸如{mathcode}和{urlmathcode}等占位符。

来源：src/_locales/ko/messages.json286-288

4.3. 特殊字符和转义

双美元符号（$$）用于在应用程序中表示单个美元符号，如多条消息描述中所述。这对于 TeX 数学表达式尤其重要。

来源：src/_locales/ko/messages.json272-274

5. 支持的语言

Markdown Here 当前支持以下语言：

语言代码	语言名称	文件位置
en	英语	src/_locales/en/
ko	韩语	src/_locales/ko/
ja	日语	src/_locales/ja/
de	德语	src/_locales/de/
tr	土耳其语	src/_locales/tr/
it	意大利语	src/_locales/it/
pl	波兰语	src/_locales/pl/

每种语言的翻译完整度不同。主要源语言是英语，所有其他翻译均由此派生。

来源：src/_locales/ko/messages.json1-355 src/_locales/ja/description.txt1-24 src/_locales/tr/messages.json1-355 src/_locales/de/messages.json1-356 src/_locales/it/messages.json1-355 src/_locales/pl/messages.json1-355

6. 翻译工作流程

添加或更新翻译的过程遵循以下通用工作流程：

6.1. 翻译贡献

如多个本地化文件中所述，Markdown Here 欢迎翻译贡献：

"options_page__contributing_2": {
  "message": "Help make Markdown Here available in your language. <a href=\"https://github.com/adam-p/markdown-here/blob/master/CONTRIBUTING.md#translation\" target=\"_blank\">Translations are welcome.</a>"
}

来源：src/_locales/ko/messages.json93-95

7. 测试本地化实现

测试本地化实现包括验证以下内容：

所有 UI 元素均以翻译后的语言正确显示
特殊字符正确渲染
UI 布局适应不同语言的文本长度变化
HTML 格式在需要时得到保留
占位符被动态内容正确替换

应在每个受支持的浏览器中使用每种受支持的语言测试扩展，以确保在所有平台上都能正常运行。

8. 常见本地化问题

8.1. 文本长度差异

翻译后的文本长度通常与原文不同，这可能会影响 UI 布局。例如，“Markdown Toggle”等按钮在不同语言中可能会显著变长或变短。

8.2. 从右到左 (RTL) 语言

虽然当前文件中未明确支持，但 RTL 语言需要对布局和文本方向进行特殊处理。

8.3. 字符编码

某些语言，特别是韩语和日语等东亚语言，可能需要特定的字符编码考量才能正确显示。