有用的译者注释会说明标签的含义、显示位置，以及用户使用它时会发生什么。本指南将介绍如何在 Xcode 中为一个简单的 Mac 形状浏览器编写并附加这些注释，其中使用的是虚构的英文标签。

译者注释应该说明什么？

从译者需要做出的判断入手。像 Round 这样的简短标签没有明确说明语法角色和预期含义。注释可以指出它是描述形状类别的形容词，并说明它显示在一组预览图上方。Apple 建议通过注释说明字符串在界面中的使用位置和方式。探索字符串目录

对于负责准备 Mac 应用标签以供翻译的人来说，具体任务是把每个有歧义的字符串转化为简短、完整的说明。译者应当无需查阅源代码，就能理解字符串的用途。

可以使用这份四部分写作指南。它是根据 Apple 的指导总结出的编辑方法，并非 Apple 要求采用的注释格式：

部分 要回答的问题 示例细节
含义 源文案指的是什么？ Round 描述的是轮廓呈曲线的形状。
界面角色 这是什么类型的界面文本？ 显示在形状预览上方的类别标题。
行为或位置 会发生什么，或它周围有什么？ Expand 会在预览图下方显示详细信息。
可变内容 每个插入值可能包含什么？ 第一个值是形状名称；第二个值是集合名称。

只写会影响理解的部分。静态标题无需解释操作。对于按钮，应清楚说明点击后会发生什么。对于包含两个插入名称的消息，应说明这两个名称之间的关系。

Apple 特别建议说明界面元素、周围的界面，以及占位符所代表的内容。将这些细节作为实用的翻译背景信息。跟着示例学习：使用 Xcode 探索本地化

将含糊的注释改写为实用的消息说明

以下示例来自一个虚构的 Mac 形状浏览器。每条改进后的注释都描述了假定且明确的界面行为；使用这些文案前，请根据实际控件调整相关行为。

源标签 不充分的注释 更实用的注释
Shapes 形状标签。 侧边栏导航项，打开几何形状列表。复数名词。
Round 形状文本。 显示在轮廓呈曲线的形状预览上方的类别标题。描述这些形状的形容词。
Expand 按钮标题。 形状预览下方的按钮，点击后会在预览下方显示详细信息。表示操作的动词。
Selected 选择标签。 当前选中用于预览的形状旁边显示的状态。描述该形状的当前状态。

不充分的版本只是重复译者已经能看到的信息。更好的版本补充了缺失的关系：形容词描述的是哪个对象、按钮会显示什么内容，或哪个项目处于某种状态。

在英语中，名词指称事物，形容词描述事物，祈使动词则指示执行某项操作。这些区别有助于解释简短的界面文案。例如，在此示例中，Selected 描述的是已有状态；如果按钮上写的是 Select，则表示要求用户执行操作。请说明界面所需的具体含义。

注释应当具体。对于 Expand，请说明控件会显示详细文本、放大预览图，还是展开侧边栏分组。直接说明操作比笼统地说它会让某个东西变大更实用。

避免强加不必要的英语格式规则。如果界面需要简短的类别标题，请说明这一点。不要凭空规定字符数上限，也不要要求译文保留英语语序。只有在确知存在实际布局限制时，才记录该限制。

在 SwiftUI 中添加译者注释

Apple 将 Text 的 comment: 参数列为添加翻译提示的方式。如果某个控件便捷的字符串初始化器无法提供所需注释，可以使用它的内容构建器，并显式指定一个 Text 视图。Apple 以 Label 演示了这种模式，并说明许多 SwiftUI 控件都支持这种做法。为视图准备本地化

以下完整示例是一个小型 macOS SwiftUI 应用。在 Xcode 中，使用 SwiftUI 创建 macOS 应用项目，将部署目标设为 macOS 13 或更高版本，然后用这个单文件替换自动生成的应用和内容视图代码。只保留一个应用入口点。示例使用固定的虚构名称，并在用户点击 Expand 时显示一条详细说明。

import SwiftUI

@main
struct ShapeCommentDemoApp: App {
    var body: some Scene {
        WindowGroup {
            ShapeBrowserView()
        }
    }
}

struct ShapeBrowserView: View {
    @State private var showsDetails = false

    private let shapeName = "Circle A"
    private let collectionName = "Shape Set A"

    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text(
                "Round",
                comment: "Category heading above previews of shapes with curved outlines. Adjective describing the shapes."
            )
            .font(.headline)

            Circle()
                .fill(Color.blue)
                .frame(width: 80, height: 80)

            Text(
                "\(shapeName) in \(collectionName)",
                comment: "Caption below a shape preview. The first value is the shape name; the second is the collection containing it. Sample names: Circle A and Shape Set A."
            )

            Button {
                showsDetails = true
            } label: {
                Text(
                    "Expand",
                    comment: "Button below a shape preview that reveals its details beneath the preview. Verb expressing an action."
                )
            }
            .disabled(showsDetails)

            if showsDetails {
                Text(
                    "A shape with a curved outline.",
                    comment: "Detail sentence revealed below the preview after clicking Expand. Describes the displayed circle."
                )
            }
        }
        .padding(24)
        .frame(minWidth: 360, minHeight: 300)
    }
}

我们已对照文档中的 API 用法检查此示例；由于当前环境没有 Swift 工具链，因此未在此处编译或运行。

对于在 SwiftUI 视图之外创建的面向用户的字符串，Apple 记录了 String(localized:comment:)。使用本地化 API 的注释参数为消息附加上下文。如果查找键和默认源值需要不同，Apple 也支持分别指定它们。准备应用文本以供翻译

按含义和关系说明插入值

示例中的说明文字包含两个 Swift 插值：\(shapeName) 和 \(collectionName)。Swift 插值会将表达式的值插入字符串字面量中。变量名称属于源代码；对译者的说明仍应让看不到这些名称的人也能理解。字符串和字符

对于示例中的虚构值，英文说明文字为 Circle A in Shape Set A。注释说明了插入值的顺序及其关系：一个值表示形状，另一个值表示包含该形状的集合。这比单纯说明有两个字符串参数更有用。

检查含插值的消息时，请问自己三个问题：

  1. 每个位置可能出现哪类内容：名称、数量，还是其他类型的值？
  2. 这些值之间有什么关系？
  3. 对应用能够提供的所有值，注释是否都准确？

请明确标示示例只是样例。这里的 Circle A 和 Shape Set A 用于说明参数各自的作用。它们并不规定必须采用哪种译法，也不构成可能名称的完整列表。

数量需要单独决定实现方式。如果之后添加类似 3 shapes 的说明文字，注释可以解释统计的对象，但语法变体应放在目录中处理。Apple 记录了如何对插值数量使用 Vary by Plural，包括分别设置英语形式，例如 1 item 和 2 items。使用字符串目录本地化和设置文本变体

在 Xcode 中查找并检查注释

要将源代码注释与目录关联起来，请按照 Apple 记录的工作流程操作：

  1. 选择 File > New > File from Template。
  2. 筛选 string，在 Resource 下选择 String Catalog，并使用默认名称 Localizable 创建文件。
  3. 选择 Product > Build，提取可本地化的字符串。
  4. 在项目导航器中选择 Localizable.xcstrings。
  5. 选择 Editor > Assistant，然后选择一个键，在目录旁边检查它的源代码。使用字符串目录本地化和设置文本变体

检查目录中的注释是否符合实际用法。在示例中，Round 应说明它是类别标题，Expand 应说明它会显示详细信息。如果字符串缺失，请检查代码是否使用了可本地化 API，以及是否启用了 Use Compiler to Extract Swift Strings。Apple 指出，基于编译器提取 Swift 字符串需要启用此构建设置。探索字符串目录

Apple 也支持直接在字符串目录的注释列中编辑上下文。Xcode 26 引入了自动生成注释的功能；当前文档介绍了按住 Control 键点按某个键，然后选择 Generate Comment。如果你的环境中没有此选项，可以在代码中附加注释，或在目录中填写注释。跟着示例学习：使用 Xcode 探索本地化、使用字符串目录本地化和设置文本变体

请根据界面行为检查生成的文案。即使描述准确指出了按钮，仍可能需要进一步明确其对象或结果。在此示例中，关键区别是 Expand 会在预览下方显示一条详细说明。

判断含义相同的标签是否可以共用上下文

英语拼写相同并不能证明含义相同。假设另一个屏幕中的 Round 是将数值四舍五入的操作。若将这种用法与形状类别标题合并，就会要求同一个目录条目描述两种不同的语法角色。

Apple 说明，可本地化字符串具有查找键，并属于某个表；键在其所属表内必须唯一。Apple 的 Swift 文档还提供了使用独立键和默认源值的受支持方式。如果不同含义需要分别翻译，即使它们显示的英语文案相同，也应使用不同的键。探索字符串目录、准备应用文本以供翻译

一个实用的判断方法是：看一条注释能否准确解释所有用法。如果含义和界面角色始终一致，共用上下文可能合适。如果注释不得不描述彼此无关的操作，就应重新考虑键的结构。这是根据 Apple 的键和表模型得出的设计推论，并非要求每个控件都必须使用独立字符串。

交付标签前，请脱离源代码单独阅读它的注释。译者应能据此识别预期含义，在概念上了解文本在界面中的位置，并理解任何插入内容。每当标签的行为或角色发生变化时，都要修改注释，确保说明仍符合用户实际看到的界面。

来源