Fluent 审阅者指南¶

本文档旨在为开发者和审阅者在处理 FTL (Fluent) 文件时提供指南。因此，它并非旨在替代有关 Fluent 的现有详尽文档。

Herald 用于将 fluent-reviewers 组设置为阻止任何修改提交到 Phabricator 的 FTL 文件的补丁的审阅者。来自该组执行审阅的人员将必须手动设置其他审阅者为阻止，如果原始开发者最初没有这样做。

提示

如有疑问，您应始终联系 l10n 团队以获取说明。

消息标识符¶

虽然在 Fluent 中可以在消息标识符中使用小写和大写字符，但在 Gecko 中的命名约定是使用小写和连字符（kebab-case），避免使用 CamelCase 和下划线。例如，allow-button 应优于 allow_button 或 allowButton，除非存在技术约束 - 例如从外部源在运行时生成的标识符 - 使此操作不切实际。

在导入多个 FTL 文件时，所有消息在 Fluent 包中共享相同的范围。因此，建议在消息标识符本身中添加范围：使用 cancel 作为标识符会增加发生冲突的可能性，save-dialog-cancel-button 将使这种情况不太可能发生。

消息标识符也用作运行时错误发生时的最终回退。拥有描述性的消息 ID 将使此类回退对用户更有用。

注释¶

当消息包含可替换项（变量）时，应始终包含一个注释来解释变量的格式以及将用什么内容替换它。这是建议用于此类注释的格式

# This string is used on a new line below the add-on name
# Variables:
#   $name (String) - Add-on author name
cfr-doorhanger-extension-author = by { $name }

默认情况下，注释绑定到紧随其后的消息。Fluent 支持文件级和组级注释。请注意，组注释将应用于该注释之后的所有消息，直到文件末尾。如果情况并非如此，则需要通过添加一个空注释（##）或将消息部分移动到文件末尾来“重置”组注释。

注释对于本地化人员至关重要，因为他们不会将文件视为整体，或将更改视为较大补丁的一部分。他们的工作一次发生在一个消息上，上下文仅由注释提供。

许可证标题是独立的注释，即前缀为单个 #，并且注释后至少跟一个空行。

现有消息的更改¶

如果以下情况发生，则必须更新消息标识符

句子的含义已更改。
您正在更改消息的形态，通过添加或删除属性。

消息在整个本地化工具链中通过其 ID 进行识别。因此，无需更改属性名称。

如果您的更改仅与英文相关 - 例如，更正印刷错误或使字母大小写一致 - 那么通常无需更新消息标识符。

在是否需要新 ID 之间存在灰色区域。在某些情况下，需要查看所有现有翻译才能确定新 ID 是否有益。如有疑问，您应始终联系 l10n 团队。

更改消息 ID 将使现有翻译失效，新消息将在所有工具中报告为缺失，并且本地化人员将不得不重新翻译它。这是确保本地化人员更新现有本地化以及运行时停止使用过时翻译的唯一可靠方法。

您还必须更新源代码中使用该消息标识符的所有实例，包括本地化注释。

消息中的非文本元素¶

当消息包含非文本元素 - 例如锚点或图像 - 时，请确保它们具有与之关联的 data-l10n-name。其他属性，例如锚点的 URL 或 CSS 类，不应在 FTL 文件中公开以进行本地化。更多详细信息可以在专门介绍 DOM 叠加层的此页面中找到。

如果您的代码使用 fluent-react，则此信息不相关，其中 DOM 叠加层的工作方式不同。

消息引用¶

考虑以下示例

newtab-search-box-search-the-web-text = Search the Web
newtab-search-box-search-the-web-input =
    .placeholder = { newtab-search-box-search-the-web-text }
    .title = { newtab-search-box-search-the-web-text }

这似乎减少了本地化人员的工作量，但实际上并没有帮助

对引用消息 (newtab-search-box-search-the-web-text) 的更改将需要为所有引用它的消息提供一个新的 ID。
翻译记忆可以帮助匹配文本，而不是消息引用。

另一方面，如果例如您想在消息中引用 UI 的另一个元素，则此方法很有用

help-button = Help
help-explanation = Click the { help-button} to access support

这强制执行一致性，并且如果 help-button 发生更改，则无论如何都需要更新所有其他消息。

术语¶

Fluent 支持一种特定类型的消息，称为术语。术语类似于常规消息，但它们只能用作其他消息中的引用。它们最适合用于定义词汇和词汇表项，这些词汇表项可以在整个产品的本地化中一致使用。

术语通常用于品牌名称，例如 Firefox 或 Mozilla：它允许将它们放在一个易于识别的位置，并在本地化未使用它们时发出警告。它有助于强制执行一致性和品牌保护。如果您只需要从另一条消息中引用一条消息，则不需要术语：允许消息之间的交叉引用，但不要滥用，如前所述。

变体和复数¶

考虑以下示例

items-selected =
    { $num ->
        [0] Select items.
        [one] One item selected.
       *[other] { $num } items selected.
    }

在此示例中，不能保证所有本地化都包含此变体，因为变体在设计上是私有的。此示例的正确方法是为 0 案例提供单独的消息

# Separate messages which serve different purposes.
items-select = Select items
# The default variant works for all values of the selector.
items-selected =
    { $num ->
        [one] One item selected.
       *[other] { $num } items selected.
    }

根据经验法则

仅当默认变体对选择器的所有可能值都有意义时才使用变体。
代码不应依赖于特定变体的可用性。

更多关于选择器和变体滥用的示例可以在此 wiki中找到。

通常，还应避免将选择器放在句子的中间，如下例所示

items-selected =
    { $num ->
        [one] One item.
       *[other] { $num } items
    } selected.

1 仅在您想涵盖字面数字的情况下使用。如果是标准复数，则应使用 one 类别表示单数。还要确保始终将变量作为数字传递给这些消息，而不是作为字符串。

访问键¶

以下是访问键的简单潜在示例

example-menu-item =
    .label = Menu Item
    .accesskey = M

访问键用于菜单，以帮助提供简单的键盘快捷键访问。它们对高级用户和有无障碍需求的用户都有用。首先阅读 Windows 开发人员文档中的访问键指南非常有帮助，因为它概述了 Windows 应用程序的最佳实践。

操作系统之间存在一些差异。Linux 大多遵循与 Windows 相同的做法。但是，macOS 通常对访问键的支持不佳，尤其是在菜单中。

选择访问键时，重要的是它相对于当前 UI 层次是唯一的。最好避免使用具有下降部分的字母，例如 g、j、p 和 q，因为这些字母在 Windows 或 Linux 中不会很好地带下划线。其他有问题的字符是狭窄的字符，例如 l、i 和 I。在无衬线字体中，下划线可能不如其他字母可见。

代码检查器¶

mach lint 包含一个 l10n 代码检查器，称为 moz-l10n-lint。开发人员可以在本地运行它，也可以在 Treeherder 上运行：在 Phabricator 上 diff 的“构建状态”部分，打开 Treeherder 作业链接，查找 l1nt 作业。

除了显示由语法错误引起的错误和警告外，它还特别重要，因为它还会检查没有新 ID 的消息更改，以及与用于发布 Firefox 本地化版本的跨通道存储库的冲突。

警告

目前，存在一个问题阻止在 Phabricator 中显示警告。可以使用 ./mach lint -l l10n -W 在本地运行检查。

从旧版或 Fluent 文件迁移字符串¶

如果补丁将旧版字符串（.properties、.DTD）迁移到 Fluent，则还应包含一个将现有字符串迁移到 FTL 消息的方案。如果补丁将现有的 Fluent 消息迁移到不同的文件，或者更改了现有消息的形态而没有实际更改内容，则同样适用。

有关如何编写和测试迁移方案的文档可在此页面中找到。