要在 Mac 上验证翻译中的占位符，请将每个参数的位置、类型和预期用途与源消息进行比较。使用 Xcode 的不匹配诊断，然后检查复数替换，并用不同的示例值测试渲染后的标签。

本指南适用于在 Xcode 中审阅 Mac 应用本地化标签的人员。任务是根据应用提供的值，检查一条消息及其翻译。以下所有标签都是虚构的英文示例；它们用于说明格式机制，并非实际翻译。

消息的参数约定包含哪些内容？

参数约定是一份审阅记录，用于描述消息接收的值：它们的位置、格式类型、含义和预期用途。这是一份依据源代码和目录整理的实用检查清单，而不是单独的 Apple 文件格式。

Swift 的 String.LocalizationValue 支持包含插值运行时值的可本地化字符串。其文档还区分了将源文本用作本地化键，以及提供单独的键和默认值这两种方式。因此，仅凭标识符可能无法看出消息的参数：请检查默认源文本及其调用位置。String.LocalizationValue

请看格式字符串 Added %lld items to %@。在这个示例中，应用先提供一个整数计数，随后提供一个由对象表示的集合标签。编辑翻译前，请先记下参数约定：

参数位置 含义 预期格式 示例值
1 添加的项目数 %lld 7
2 目标集合标签 %@ Canvas

Apple 的格式参考将 %@ 定义为对象转换，将 %d 定义为有符号 32 位整数，将 %f 定义为 double 转换，并将 ll 定义为 long long 的整数长度修饰符。文档还介绍了 %1$@ 之类的位置形式。请保留完整的类型信息；将 %lld 改为 %d 会改变预期的整数类型。该参考文档已归档，因此请将它与当前的目录文档一并用于了解格式语法。String Format Specifiers

即使参数类型相同，也要在审阅记录中写明它们的含义。对于 Moved %@ to %@，仅检查类型无法区分项目标签和目标标签。语法正确也必须确保值与文字的对应关系正确。

如何在 Xcode 中找到权威源？

在 Xcode 中打开项目，并找到包含该消息的目录。如果源代码已更改，请选择 Product > Build 以刷新提取的字符串。在项目导航器中选择目录，然后选择 Editor > Assistant，再选择消息键以查看其源文本。Apple 在有关查找和更新目录条目的工作流程文档中介绍了这些步骤。Localizing and varying text with a string catalog

检查调用位置实际提供了哪些值、顺序如何，以及使用了哪种本地化 API。Apple 推荐使用 String(localized:) 等可本地化 API；带有单独 defaultValue 的初始化器会将第一个参数用作键，第二个参数用作默认源字符串。如果由 collection.added.summary 这类中性标识符关联消息，这一点就很重要。Preparing your app’s text for translation

请将三项信息放在一起记录：目录和键、默认源文本，以及按顺序排列的参数含义和类型。如果这些信息不一致，请先解决差异，再调整翻译。否则，你可能会让翻译匹配过时的源文本，而不是应用当前提供的输入。

也请为后续编辑提供上下文。Apple 支持为可本地化字符串添加注释以说明其用途。一条有用的虚构注释可以说明，参数 1 是项目计数，参数 2 是目标集合标签。这能向本地化人员提供格式说明符无法表达的信息。Preparing your app’s text for translation

如何检查计数、类型和参数位置？

Apple 为字符串目录引入了针对常见问题的验证功能，其中包括格式说明符不匹配，并为某些问题提供修复建议。请检查 Xcode 对该条目显示的诊断。将修正建议视为语法修复方案，并确认它保留了消息含义。Build multilingual-ready apps

对于没有复数替换的简单消息，请按以下顺序审阅：

  1. 找出源文本和候选文本中所有会使用参数的占位符。
  2. 将每个占位符对应到参数位置。
  3. 将占位符的完整格式类型与约定进行比较。
  4. 检查每个必需值是否出现在文字所预期的位置。
  5. 逐一调查新增、遗漏或重复的引用。

位置表示法允许翻译调整语序，同时保留参数身份。在 %2$@: added %1$lld items 中，第一个可见占位符引用参数 2，第二个引用参数 1。Apple 文档介绍了 n$ 位置语法。String Format Specifiers

下表适用于上述两个参数的示例约定。这些是建议的审阅结论，并非运行 Xcode 得出的结果：

候选格式文本 审阅结论 原因
Added %lld items to %@ 符合简单约定 先是计数，后是目标位置
%2$@: added %1$lld items 调整顺序后符合 显式位置保留了两个参数各自的身份
Added %d items to %@ 修正整数类型 参数 1 不再使用预期的长度修饰符
Added %lld items 调查遗漏 缺少此消息所需的目标位置
Added %1$lld items to %1$@ 修正引用 参数 1 被以相互冲突的类型引用；参数 2 缺失
Added %1$lld items to %2$@ (%2$@) 检查重复 共出现三次，但只引用了两个不同参数

请将出现次数与不同参数的数量分开计算。最后一行特意展示了这种区别：重复参数 2 不会产生第三个输入值。这样的重复是否适合文字内容，属于编辑判断。就本任务而言，在确认其用途之前应先标记出来。

同样，不要把每个百分号都算作参数。Apple 将 %% 定义为字面百分号。格式标签 Scale: %lld%% 包含一个值占位符和一个转义的百分号。String Format Specifiers

为什么复数替换需要采用不同的检查方式？

复数消息除了要审阅显示文本，还需要检查选择机制。Apple 在介绍字符串目录的讲解中说明，替换项可以包含复数形式的字典。检查器会显示控制参数的位置和 C 风格格式说明符。因此，即使某个分支没有以数字形式显示参数，该替换项仍可能依赖该参数。Discover String Catalogs

对于虚构的项目计数消息，请比较 One item added 和 %lld items added。第一个分支将数量写成文字，第二个分支则显示数字。如果要求每个分支中可见占位符数量完全相同，就会不必要地拒绝第一个分支。Apple 文档对 strings 字典行为的说明明确指出，复数形式可以省略数字格式说明符，并且可以选择将数字写成文字。Stringsdict file format

请按以下方式逐分支审阅：

  • 在检查器中核对替换项的控制参数位置和类型。
  • 检查目标本地化中存在的每个复数分支。
  • 将每个显示的占位符与其引用的参数进行核对。
  • 通过分支文字说明任何省略的数字显示。
  • 单独检查其他消息参数；将计数写成文字并不能解释集合标签为何缺失。

如果有两个独立变化的计数，请保留它们各自的作用。关于项目和集合的虚构消息需要让项目计数控制项目替换，让集合计数控制集合替换。Apple 文档介绍了同一消息中的多个替换项，并说明运行时输出会组合各自选中的复数形式。Discover String Catalogs

如何在 Mac 上确认修正后的消息？

修复条目后，构建应用并检查是否还有目录诊断。然后在目标本地化环境中运行相关界面。Apple 支持的工作流程是：选择 Product > Scheme > Edit Scheme，选择 Run，打开 Options，选择 App Language 和相应的 App Region，点击 Close，然后运行所选目标。Testing localizations when running your app

选择能让交换一目了然的示例值。对于两个计数参数，请使用不同的数字，例如 2 和 7。对于两个文本参数，请使用不同的标签，例如 Tile 和 Canvas。这些都是示例测试输入，其目的是显示每个提供的值出现在消息的哪个部分。

对于复数消息，请测试能够触发待审分支的值。如果两个替换项独立变化，请提供一些组合：每次改变一个计数，同时保持另一个不变。检查所选文字以及每个显示值的位置。某个组合渲染成功，并不代表其他分支也已检查。

请将翻译状态与参数约定检查分开处理。Apple 说明，目录中的绿色勾号表示已输入文本后的“已翻译”状态。请记录实际执行的检查——参数映射、类型比较、分支检查和渲染示例——不要将该状态指示器视为这四项检查的证据。Localizing and varying text with a string catalog

当占位符对应到预期的输入参数、参数类型相符，并且任何分支特有的省略或重复都有明确解释时，这条消息就可以进入下一步。将这份简明的参数约定放在消息旁边，后续评估源代码或翻译的改动时会更容易。

来源