给 AI 的本地化任务说明：保留键名、占位符和复数规则

一份有用的本地化任务说明，会将译者可以修改的文字，与应用所依赖的标识符和行为分开。请 AI 代理翻译之前，先提供完整消息、命名参数、不同数量的处理情况，以及消息所在的界面情境。

以一个虚构的文件上传界面为例。它需要告诉用户有多少文件已就绪，以及哪个文件上传失败。即使译文流畅，只要改了参数名，或把失败译成成功，这个界面仍然可能出错。

以下示例使用 ICU4J 77.1 经典 MessageFormat 语法。JSON 对象只是示例中的消息目录容器，并不是 ICU 资源文件格式，也不是库的加载 API。如果应用使用其他消息库，请先确认其语法。ICU 指南解释了完整消息的格式化、命名参数和复数分支；77.1 源码参考则明确了此处采用的版本。

翻译之前，先定义消息约定

下面是本例完整的英文源消息目录：

{
  "files.ready": "{count, plural, =0 {No files are ready.} =1 {# file is ready.} other {# files are ready.}}",
  "upload.failed": "Could not upload {fileName}. Try again.",
  "folder.open": "Open {folderName}"
}

这三个键用于标识应用消息，在所有语言区域中都保持一致。值采用完整消息，译者便可以调整语序，而不必协调多个零散片段。

键名	出现位置	参数与约束	需要保留的含义
`files.ready`	上传按钮上方的状态	`count`：非负整数	文件已就绪；不表示上传成功
`upload.failed`	一次尝试失败后显示的错误	`fileName`：普通文件名标签	本次尝试失败，用户可以重试
`folder.open`	用于打开文件夹的按钮	`folderName`：普通文件夹名称标签	动作标签，不是在报告文件夹已经打开

在本练习中，文件名和文件夹名称是用户提供的标签。翻译它们周围的句子，不翻译这些标签。值的渲染和转义由应用的输出层负责；消息翻译不能决定任意输入是否可以安全地作为 HTML 渲染。

这份小约定能避免“把上传文案译得自然一点”这样的模糊要求。它告诉代理，每句话的作用是什么，哪些部分属于数据。

翻译完整消息，同时保留约定

下面是一份示例性的简体中文对应目录：

{
  "files.ready": "{count, plural, =0 {没有就绪的文件。} =1 {已有 # 个文件就绪。} other {已有 # 个文件就绪。}}",
  "upload.failed": "无法上传 {fileName}。请重试。",
  "folder.open": "打开 {folderName}"
}

语序可以调整。键名、参数名和预期动作不能悄悄改变。

显式的 =0 和 =1 是为这条具体消息作出的选择：零使用单独的状态文案，一在英文中使用单数句子，其余数量使用 other。这并不是适用于所有语言的完整复数规则配方。其他语言区域和消息可能需要额外类别和不同措辞。经典 ICU 复数模式要求有 other 分支。应请目标语言审阅者把整个模式作为一个整体评估，而不是把英文语法类别照搬到每种语言中。

审查具体错误，不只看整体流畅度

错误修改	为什么会出错	如何修正
将 `upload.failed` 改成翻译后的键名	应用查找消息时仍使用原键名	保留 `upload.failed`，翻译它的值
将 `{fileName}` 换成 `{文件名}`	调用方提供的是 `fileName`，不是新标识符	原样保留 `{fileName}`
从复数模式中删除 `other`	模式失去了必需的兜底分支	保留 `other`，并在其中提供完整的目标语言消息
将“Could not upload”译成“Upload complete”	界面现在报告的是相反的结果	保留失败和重试的含义
将 `Open {folderName}` 拆成前缀和单独的名词	实现方式把一种语言的语序强加给了另一种语言	保留一条包含该参数的完整消息

有些改动需要先提问，而不宜自动修正。例如，短按钮可能需要更简练的译文，但去掉动作对象可能让几个相邻按钮无法区分。如果这些约束会影响选择，请提供可用宽度和相邻标签。

提供审阅者可以检查的具体案例

下面是手工编写的预期字符串，不是从 ICU 运行时捕获的输出：

语言与输入	预期显示
英文，`count = 0`	No files are ready.
英文，`count = 1`	1 file is ready.
英文，`count = 3`	3 files are ready.
简体中文，`count = 0`	没有就绪的文件。
简体中文，`count = 1`	已有 1 个文件就绪。
简体中文，`count = 3`	已有 3 个文件就绪。
英文，`fileName = budget.csv`	Could not upload budget.csv. Try again.
简体中文，`fileName = budget.csv`	无法上传 budget.csv。请重试。

这些预期覆盖了含义和参数的保留情况。下一步实现检查，应当通过应用实际选用的格式化器加载消息目录，并渲染受影响的界面。这样才能发现语法、调用方参数和布局问题；并排审阅文本本身无法确认这些方面。

一份可以调整复用的完整任务说明

任务：将附件中虚构文件上传功能的消息从英文
本地化为简体中文。使用 ICU4J 77.1 经典 MessageFormat 语法。
JSON 消息目录是本例的容器；不要编造加载 API。

情境：
- files.ready 是上传前的状态，不是上传成功消息。
- upload.failed 在一次尝试失败后出现，并提供重试提示。
- folder.open 是用于打开指定文件夹的按钮。

保留：
- 完全相同的三个键名及其消息含义。
- 参数名 count、fileName 和 folderName。
- count 为非负整数；标签保持为调用方传入的原始数据。
- 本例 files.ready 中显式的 =0、=1 和 other 分支。
- 使用完整消息，不拼接翻译后的片段。

交付：
1. 完整的目标消息目录，不增加或遗漏键名。
2. 对有意义的措辞或语法选择作出解释。
3. 数量为 0、1、3，以及 fileName 为 budget.csv 时的预期显示。
4. 对缺少的界面情境提出问题，不自行编造情境。

检查：
- 对照源目录，比较键名集合和参数名。
- 条件具备时，使用应用实际采用的库进行解析和格式化。
- 分别检查失败／动作含义与目标语言语法。
- 在受影响界面中检查长标签和布局。

范围：仅做消息本地化。不要修改调用方、依赖、
渲染安全、语言区域回退行为或应用发布设置。
如果无法运行格式化器，就将显示内容标为预期。

接受译文之前，要检查键名集合、参数、数量分支、含义和实际渲染的界面。每一项都能发现不同类型的错误。句子即使读起来很漂亮，也可能仍在向应用索取错误的变量。