moz.l10n

这是一个Python工具和实用程序的库，用于处理本地化文件，主要用于Mozilla的内部使用。

核心思想是建立Message和Resource作为本地化和本地化消息及资源的格式无关表示，以便可以对它们应用像linting和transforms这样的操作。

Message和Resource表示借鉴了Unicode MessageFormat 2规范和Message资源规范的工作。

对XML格式的支持（android，xliff）是可选的额外功能；要支持它们，请作为moz.l10n[xml]安装。

命令行工具

有关使用详细信息，请使用每个命令的--help参数。

l10n-build

为发布构建本地化文件。

迭代由--config定义的源文件，从--base读取本地化源，并写入--target。为每个--locales修剪出源文件中不存在的所有注释和消息。为任何在目标区域中缺失的文件添加空文件。

l10n-build-file

为发布构建单个本地化文件。

使用--source文件作为基线，应用--l10n本地化来构建--target。删除所有不在源文件中的注释和消息。

l10n-compare

比较本地化与其source，这可能是一个

• 目录（使用L10nDiscoverPaths），
• 一个TOML配置文件（使用L10nConfigPaths），或
• 一个包含文件路径到消息数组的JSON文件。

l10n-fix

修复本地化资源的格式。

如果paths是单个目录，当设置了--config时，使用L10nConfigPaths迭代，否则使用L10nDiscoverPaths。如果paths不是一个单个目录，其值被视为glob表达式，支持**。

moz.l10n.paths

L10nConfigPaths

本地化配置文件的包装器。

支持在以下位置指定的格式的一个子集：https://moz-l10n-config.readthedocs.io/en/latest/fileformat.html

差异

• [build]被忽略
• [[excludes]]不受支持
• [[filters]]被忽略
• [[paths]]必须始终包含reference和l10n

不考虑.l10n-ignore文件。

L10nDiscoverPaths

自动本地化资源发现。

给定根目录，找到最有可能的参考和目标目录。

参考目录的名称类似于templates、en-US或en，并包含看起来可本地化的文件。

本地化目标根目录是一个子目录名为BCP 47区域标识符的目录，例如aa、aa-AA、aa-Aaaa或aa-Aaaa-AA。

下划线也可以用作分隔符，例如en_US。

moz.l10n.resources

提供了对多种格式的解析器和序列化器，使用通用且成熟的库来处理细节。提供了一个统一的API，以便FORMAT_parse(text)始终接受str输入，而FORMAT_serialize(resource)始终提供一个str迭代器。所有序列化器都接受一个trim_comments参数，该参数从序列化结果中删除注释，但输入类型和选项根据格式而异。

库目前支持以下资源格式

• android：Android字符串资源（strings.xml）
• dtd：.dtd
• fluent：Fluent (.ftl)
• inc：.inc
• ini：.ini
• plain_json：纯JSON (.json)
• po：Gettext (.po, .pot)
• properties：.properties
• webext：WebExtensions（messages.json）
• xliff：XLIFF 1.2，包括XCode自定义（.xlf，.xliff）

add_entries

def add_entries(
    target: Resource,
    source: Resource,
    *,
    use_source_entries: bool = False
) -> int

通过从source添加不在target中存在的条目来修改target。独立注释不会被添加。

如果设置了use_source_entries，当条目在source中与target中的不同时，将覆盖target中的条目。

条目不会被复制，所以进一步的更改将反映在两个资源中。

返回添加的条目数量。

detect_format

def detect_format(name: str | None, source: bytes | str) -> Format | None

根据输入的文件扩展名和/或内容检测输入的格式。

返回一个Format枚举值，或者如果输入不被识别，则返回None。

iter_resources

def iter_resources(
    root: str,
    dirs: list[str] | None = None,
    ignorepath: str = ".l10n-ignore"
) -> Iterator[tuple[str, Resource[Message, str] | None]]

遍历根目录下的可本地化资源。使用dirs限制搜索仅限于根目录下的某些子目录。

产生(str, Resource | None)元组，其中包含文件路径和相应的Resource，或对于无法解析为本地化资源的文件，包含None。

要忽略文件，请在 root 目录或作为 ignorepath 传入的其他位置包含一个 .l10n-ignore 文件。此文件使用 git 忽略语法，始终基于 root 目录。

l10n_equal

def l10n_equal(a: Resource, b: Resource) -> bool

比较两个资源的本地化相关内容（id、注释、元数据、消息值）。

忽略没有消息条目的部分，并忽略部分、条目和元数据的顺序。

parse_resource

def parse_resource(
    input: Format | str | None,
    source: str | bytes | None = None
) -> Resource[Message, str]

从其字符串表示形式解析资源。

第一个参数可以是显式的格式、文件路径作为字符串或 None。对于后两种类型，将尝试检测适当的格式。

如果第一个参数是字符串路径，则 source 参数是可选的，因为文件将被打开并读取。

serialize_resource

def serialize_resource(
    resource: Resource[str, str] | Resource[Message, str],
    format: Format | None = None,
    trim_comments: bool = False
) -> Iterator[str]

将资源序列化为其字符串表示形式。

如果设置了 format，则它将覆盖 resource.format 的值。

使用 trim_comments 时，所有独立和附加的注释都将被排除在序列化之外。