役立つ翻訳者向けコメントは、ラベルの意味、表示場所、使用したときの動作を説明します。このガイドでは、合成した英語ラベルを使ったシンプルなMac用シェイプブラウザを例に、Xcodeでコメントを書く方法と付ける方法を紹介します。

翻訳者向けコメントでは何を説明すべきか？

まず、翻訳者が判断しなければならないことを考えます。Roundのような短いラベルでは、文法上の役割も意図された意味も明確ではありません。コメントで、これはシェイプのカテゴリーを表す形容詞であり、プレビューのグループの上に表示されると説明できます。Appleは、文字列がインターフェイスのどこでどのように使われるかを明確にするコメントを推奨しています。文字列カタログを確認する

Macアプリのラベルを翻訳用に準備する人にとって、具体的な作業は、曖昧な文字列をそれぞれ、短く自己完結した説明に変えることです。翻訳者がソースコードをたどらなくても、その目的を理解できるようにします。

次の4項目を、文章作成の手がかりとして使ってください。これはAppleが必須としているコメント形式ではなく、Appleのガイダンスに基づく編集上の方法です。

項目 答える質問 具体例
意味 原文は何を指していますか？ Roundは、輪郭が曲線のシェイプを表します。
UI上の役割 どの種類のインターフェイス文言ですか？ シェイプのプレビューの上にあるカテゴリー見出し。
動作または場所 どのように動作するか、または何に囲まれていますか？ Expandを選ぶと、プレビューの下に詳細が表示されます。
可変コンテンツ 挿入される各値には何が入りますか？ 1つ目の値はシェイプ名、2つ目はコレクション名です。

解釈に影響する項目だけを含めてください。静的な見出しに操作の説明は必要ありません。ボタンには、クリックすると何が起きるかを明確に説明すると役立ちます。2つの名前を挿入するメッセージには、それらの関係が必要です。

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以降に設定して、生成されたアプリとコンテンツビューのコードをこの1つのファイルに置き換えてください。アプリのエントリーポイントは1つだけにしてください。このサンプルでは固定された架空の名前を使い、ユーザーが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はその方法をサポートしています。アプリのテキストを翻訳用に準備する

挿入値の意味と関係を説明する

この例のキャプションには、2つのSwift補間が含まれています。\(shapeName)と\(collectionName)です。Swiftの補間では、式の値を文字列リテラルに挿入します。変数名はソースコード上の名前です。説明は、その名前を見られない人にもわかる内容にしてください。文字列と文字

ここに示す架空の値を使うと、英語のキャプションはCircle A in Shape Set Aとなります。そのコメントでは、挿入値の順序と関係の両方を説明します。一方はシェイプの名前、もう一方はそのシェイプを含むコレクションの名前です。これは、2つの文字列引数があるとだけ説明するよりも、翻訳に役立つ情報です。

補間を含むメッセージを確認するときは、次の3つを問いかけてください。

  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. ProjectナビゲーターでLocalizable.xcstringsを選びます。
  5. Editor > Assistantを選び、キーを選択して、カタログの横にソースを表示します。文字列カタログでテキストをローカライズして変化させる

カタログのコメントを実際の用途と照らして確認します。このサンプルでは、Roundはカテゴリー見出しを説明し、Expandは詳細を表示する動作を説明する必要があります。文字列が見つからない場合は、コードがローカライズ可能なAPIを使っていることと、Use Compiler to Extract Swift Stringsが有効になっていることを確認します。Appleは、コンパイラを使ったSwift文字列の抽出にこのビルド設定が必要だとしています。文字列カタログを確認する

Appleは、String Catalogのコメント欄で直接コンテキストを編集する方法もサポートしています。コメントの自動生成はXcode 26で導入されました。現在のドキュメントでは、キーをControlキーを押しながらクリックしてGenerate Commentを選ぶ方法が説明されています。環境でそのオプションが使えない場合は、コードにコメントを付けるか、カタログに入力してください。コードと一緒に学ぶ：Xcodeでローカライズを探る、文字列カタログでテキストをローカライズして変化させる

生成された文言を、インターフェイスの動作と照らして確認します。ボタンを正しく説明していても、対象や結果を明確にする必要があるかもしれません。この例で役立つのは、Expandを選ぶとプレビューの下に詳細文が表示されるという説明です。

同じラベルが2つある場合に文脈を共有できるか判断する

英語のつづりが同じでも、意味が同じとは限りません。たとえば、別の画面で数値を丸める操作にRoundを使う場合、その用途をシェイプカテゴリーの見出しとまとめると、1つのカタログ項目で異なる文法上の役割を説明することになります。

Appleによると、ローカライズ可能な文字列にはルックアップキーがあり、テーブルに属します。キーは同じテーブル内で一意です。また、AppleのSwiftドキュメントでは、デフォルトの原文値に別のキーを使う方法も紹介されています。意味ごとに独立した翻訳が必要なら、英語の表示値が同じでも別のキーを使ってください。文字列カタログを確認する、アプリのテキストを翻訳用に準備する

実用的な判断基準は、1つのコメントですべての用途を正確に説明できるかどうかです。意味とUI上の役割が一貫しているなら、文脈を共有できる場合があります。説明するために無関係な操作まで記載しなければならないなら、キーの構成を見直してください。これはAppleのキーとテーブルのモデルから導いた設計上の判断であり、すべてのコントロールに独自の文字列が必要という規則ではありません。

ラベルを引き渡す前に、ソースコードを見ずにコメントを読んでください。翻訳者が意図された意味を特定し、インターフェイス上の表示場所を概念的に把握し、挿入されるコンテンツを理解できる内容にします。ラベルの動作や役割が変わったらコメントも更新し、ユーザーが目にするインターフェイスを正しく説明し続けるようにしてください。

出典