A useful translator comment explains what a label means, where it appears, and what happens when someone uses it. This guide shows how to write and attach those comments in Xcode for a simple Mac shape browser, using synthetic English labels.

What should a translator comment explain?

Start with the decision a translator must make. A short label such as Round leaves its grammatical role and intended meaning unclear. A comment can identify it as an adjective describing a shape category and explain that it appears above a group of previews. Apple recommends comments that clarify where and how a string is used in the interface. Discover String Catalogs

For someone preparing a Mac app’s labels for translation, the concrete task is to turn each ambiguous string into a small, self-contained explanation. The translator should be able to understand its purpose without navigating the source code.

Use this four-part writing aid. It is an editorial method derived from Apple’s guidance, rather than a required Apple comment format:

Part Question to answer Example detail
Meaning What does the source wording refer to? Round describes shapes with curved outlines.
UI role What kind of interface text is this? A category heading above shape previews.
Behavior or location What happens, or what surrounds it? Expand reveals details below the preview.
Variable content What can each inserted value contain? The first value is a shape name; the second is a collection name.

Only include parts that affect interpretation. A static heading needs no explanation of an action. A button benefits from a clear account of what clicking it does. A message with two inserted names needs the relationship between those names.

Apple specifically advises explaining the interface element, surrounding interface, and content represented by placeholders. Treat those details as practical translation context. Code-along: Explore localization with Xcode

Turn vague comments into useful message contracts

The following examples belong to an illustrative Mac shape browser. Each improved comment describes an assumed, explicit interface behavior; adapt that behavior to the actual control before using the wording.

Source label Weak comment More useful comment
Shapes Label for shapes. Sidebar navigation item that opens the list of geometric shapes. Plural noun.
Round Shape text. Category heading above previews of shapes with curved outlines. Adjective describing the shapes.
Expand Button title. Button below a shape preview that reveals its details beneath the preview. Verb expressing an action.
Selected Selection label. Status beside the shape currently chosen for the preview. Describes the shape’s current state.

The weak versions repeat what the translator can already see. The stronger versions supply missing relationships: which object the adjective describes, which content the button reveals, or which item has a particular state.

In English, a noun names something, an adjective describes something, and an imperative verb directs an action. These distinctions help explain compact interface wording. For example, Selected in this illustration describes an existing state; Select on a button would request an action. State which interpretation the interface requires.

Keep comments concrete. For Expand, explain whether the control reveals detail text, enlarges a preview, or opens a sidebar group. Naming the operation is more useful than saying that it makes something bigger.

Avoid imposing unnecessary English formatting rules. If the interface needs a concise category heading, say that. Do not invent a fixed character allowance or require the translation to preserve English word order. Document a real layout constraint only when you know it applies.

Add translator comments in SwiftUI

Apple documents the comment: parameter on Text as a way to include translation hints. When a control’s convenient string initializer does not provide the comment you need, use its content builder with an explicit Text view. Apple demonstrates this pattern for Label and explains that many SwiftUI controls support it. Preparing views for localization

The complete example below is a small macOS SwiftUI app. In Xcode, create a macOS app project using SwiftUI, set the deployment target to macOS 13 or later, and replace the generated app and content-view code with this single file. Keep only one app entry point. The sample uses fixed, synthetic names and reveals a detail sentence when the user clicks 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)
    }
}

This example has been inspected against the documented API patterns; it has not been compiled or run here because the available environment has no Swift toolchain.

For user-facing strings created outside a SwiftUI view, Apple documents String(localized:comment:). Use the localization API’s comment argument to attach the context to the message. Apple also supports a separate lookup key and default source value when those need to differ. Preparing your app’s text for translation

Explain inserted values by meaning and relationship

The caption in the example contains two Swift interpolations: \(shapeName) and \(collectionName). Swift interpolation inserts the values of expressions into a string literal. The variable names belong to the source code; the explanation should still make sense to someone who cannot see those names. Strings and Characters

For the synthetic values shown, the English caption reads Circle A in Shape Set A. Its comment explains both the order of the inserted values and their relationship: one names the shape, and one names the collection containing it. That gives more usable information than merely describing two string arguments.

When reviewing an interpolated message, ask three questions:

  1. What kind of content can appear in each position: a name, a count, or another kind of value?
  2. How do the values relate to one another?
  3. Does the comment remain accurate for every value the app can supply?

Keep examples clearly identified as samples. Here, Circle A and Shape Set A illustrate the argument roles. They do not define a required translation or an exhaustive list of possible names.

Counts require a separate implementation decision. If you later add a caption such as 3 shapes, a comment can explain what is counted, but the grammatical variants belong in the catalog. Apple documents using Vary by Plural for interpolated counts, including separate English forms such as 1 item and 2 items. Localizing and varying text with a string catalog

Find and inspect the comments in Xcode

To connect the source comments to the catalog, follow Apple’s documented workflow:

  1. Choose File > New > File from Template.
  2. Filter for string, select String Catalog under Resource, and create it with the default name Localizable.
  3. Choose Product > Build to extract localizable strings.
  4. Select Localizable.xcstrings in the Project navigator.
  5. Choose Editor > Assistant, then select a key to inspect its source beside the catalog. Localizing and varying text with a string catalog

Check the catalog’s comment against the actual use. In the sample, Round should explain a category heading, and Expand should describe revealing details. If a string is missing, check that the code uses a localizable API and that Use Compiler to Extract Swift Strings is enabled. Apple identifies that build setting as necessary for compiler-based Swift string extraction. Discover String Catalogs

Apple also supports editing context directly in the String Catalog’s comments column. Automatic comment generation was introduced in Xcode 26; current documentation describes Control-clicking a key and choosing Generate Comment. If that option is unavailable in your setup, attach a comment in code or enter it in the catalog. Code-along: Explore localization with Xcode, Localizing and varying text with a string catalog

Review generated wording against the interface behavior. A description that correctly identifies a button may still need the object or result clarified. For this example, the useful distinction is that Expand reveals a detail sentence below the preview.

Decide whether two identical labels can share context

Matching English spelling does not establish matching meaning. Suppose another screen uses Round as an action that rounds a numeric value. Combining that use with the shape-category heading would require one catalog entry to describe two different grammatical roles.

Apple explains that a localizable string has a lookup key and belongs to a table; keys are unique within their table. Apple’s Swift documentation also provides a supported way to use a distinct key with a default source value. Use separate keys when the meanings require independent translations, even if their English display values match. Discover String Catalogs, Preparing your app’s text for translation

A practical decision rule is to ask whether one comment can accurately explain every use. If the meaning and UI role remain consistent, shared context may be appropriate. If the explanation has to describe unrelated operations, reconsider the key structure. This is a design inference from Apple’s key-and-table model, rather than a rule that every control needs its own string.

Before handing off a label, read its comment without the source code. It should let the translator identify the intended meaning, locate the text conceptually in the interface, and understand any inserted content. Revise the comment whenever the label’s behavior or role changes so that the explanation continues to describe the interface the user sees.

Sources