localizationkit

localizationkit 是一个确保您的本地化字符串尽可能最佳的工具包。

包括对各种事物的测试，例如

• 检查所有字符串都有注释
• 检查注释不仅与值匹配
• 检查标记有位置指定符
• 检查不包含无效标记

还有更多即将到来。

入门

配置

要使用库，首先创建一个TOML格式的配置文件。以下是一个示例

default_language = "en"

[has_comments]
minimum_comment_length = 25
minimum_comment_words = 8

[token_matching]
allow_missing_defaults = true

[token_position_identifiers]
always = false

此配置文件将en设置为默认语言（因此这是检查注释等内容的语言，所有测试都将相对于它运行）。然后它为每个测试设置各种设置。每个[something_here]实例都指定以下设置适用于该测试。例如，测试has_comments现在将确保不仅存在注释，而且注释至少25个字符长，且至少包含8个单词。

现在您可以加载配置

from localizationkit import Configuration

configuration = Configuration.from_file("/path/to/config.toml")

本地化集合

现在我们需要准备要放入的字符串。以下是如何创建单个字符串的方法

from localizationkit import LocalizedString

my_string = LocalizedString("My string's key", "My string's value", "My string's comment", "en")

这创建了一个带有关键字、值和注释的单个字符串，其语言代码设置为en。创建更多之后（通常也是为不同的语言），可以将它们捆绑到一个集合中

from localizationkit import LocalizedCollection

collection = LocalizedCollection(list_of_my_strings)

运行测试

到此，您已经准备好运行测试

import localizationkit

results = localizationkit.run_tests(configuration, collection)

for result in results:
    if not result.succeeded():
        print("The following test failed:", result.name)
        print("Failures encountered:")
        for violation in result.violations:
            print(violation)

不运行测试

某些测试对每个人来说都没有意义。要跳过测试，您可以将以下内容添加到根配置文件中

blacklist = ["test_identifier_1", "test_identifier_2"]

规则文档

大多数测试都有可配置的规则。如果没有指定规则，将使用默认规则。

某些测试仅可选。这些将标记为此类。

注释换行符

标识符：comment_linebreaks 可选：true

检查字符串注释是否不包含换行符。包含换行符的注释可能会干扰其他工具（如dotstrings）的解析。

注释相似度

标识符：comment_similarity

检查注释与默认语言中字符串值的相似度。这是通过difflib的SequenceMatcher实现的。更多详情请见这里

Duplicate Keys

标识符：duplicate_keys

检查集合中是否存在重复键。

有注释

标识符：has_comments

检查字符串是否有注释。

注意：由于在空格处拆分以检查单词，因此仅支持具有拉丁字母风格的脚本语言进行单词检查。

有值

标识符：has_value

检查字符串是否有值。由于对于某些字符串，任何值都足够，因此它仅确保字符串不是None/null且不为空。

无效令牌

标识符：invalid_tokens

检查字符串中的所有格式令牌是否有效。

注意：此检查不是特定于语言的。它仅在大范围内工作。

键长度

标识符：key_length

检查键的长度。

注意：默认情况下，此测试不进行检查。需要设置参数为正值才能执行任何操作。

Objective-C 选项标记

标识符：objectivec_alternative_tokens 启用：true

检查字符串是否不包含 Objective-C 风格的替代位置标记。

Objective-C 似乎允许使用 %1@ 格式的位置标记，而不是 %1$@。虽然这不是非法的，但最好确保不同语言之间的一致性，以避免工具出现意外的故障等。

占位符标记说明

标识符：placeholder_token_explanation 启用：true

检查如果字符串中使用了占位符，则注释明确说明了其替换的内容。

先决条件：字符串中的每个占位符及其注释中的说明都应遵循 token_position_identifiers 规则。

Swift 插值

标识符：swift_interpolation 启用：true

检查字符串是否不包含 Swift 风格的插值值，因为这些值无法本地化。

标记匹配

标识符：token_matching

检查字符串中的标记是否在所有语言中匹配。例如，如果你的英文字符串是 "Hello %s"，但你的法语字符串是 "Bonjour"，这将标记法语字符串中缺少标记。

标记位置标识符

标识符：token_position_identifiers

检查每个标记是否带有位置指定符。例如，%s 不被允许，但 %1$s 是允许的。标记可以在不同语言中移动，因此位置指定符非常重要。

贡献

本项目欢迎贡献和建议。大多数贡献都需要你同意贡献者许可协议 (CLA)，声明你有权，并且实际上确实授予我们使用你的贡献的权利。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当你提交拉取请求时，CLA 机器人会自动确定你是否需要提供 CLA，并相应地装饰 PR（例如，状态检查、注释）。只需遵循机器人提供的说明即可。你只需在整个使用我们的 CLA 的所有存储库中这样做一次。

本项目已采用 Microsoft 开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或联系 opencode@microsoft.com 以提出任何额外的问题或评论。