유용한 번역자 주석은 레이블의 의미, 표시 위치, 사용했을 때 발생하는 동작을 설명합니다. 이 가이드에서는 합성 영어 레이블을 사용해 간단한 Mac 도형 브라우저의 주석을 작성하고 Xcode에서 연결하는 방법을 보여줍니다.

번역자 주석에는 무엇을 설명해야 하나요?

번역자가 내려야 할 결정부터 시작하세요. Round처럼 짧은 레이블은 문법적 역할과 의도한 의미가 불분명합니다. 주석을 통해 이 단어가 도형 범주를 설명하는 형용사이며 미리 보기 그룹 위에 표시된다고 설명할 수 있습니다. Apple은 인터페이스에서 문자열이 어디에, 어떻게 사용되는지 명확히 하는 주석을 권장합니다. 문자열 카탈로그 알아보기

Mac 앱의 레이블을 번역할 수 있도록 준비하는 사람의 구체적인 작업은 모호한 문자열마다 짧고 독립적으로 이해할 수 있는 설명을 덧붙이는 것입니다. 번역자는 소스 코드를 찾아보지 않아도 레이블의 목적을 이해할 수 있어야 합니다.

다음 네 가지 항목을 글쓰기 보조 도구로 활용하세요. 이는 Apple이 요구하는 주석 형식이 아니라 Apple의 지침에서 도출한 편집 방법입니다.

항목 답할 질문 예시 세부 정보
의미 원문의 표현은 무엇을 가리키나요? Round는 윤곽선이 곡선인 도형을 설명합니다.
UI 역할 어떤 종류의 인터페이스 텍스트인가요? 도형 미리 보기 위에 있는 범주 제목입니다.
동작 또는 위치 어떤 동작이 일어나거나, 주변에 무엇이 있나요? 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. 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를 누르면 미리 보기 아래에 세부 설명이 표시된다는 점입니다.

동일한 레이블 둘이 맥락을 공유할 수 있는지 판단하기

영어 표기가 같다고 해서 의미도 같다는 뜻은 아닙니다. 다른 화면에서 Round가 숫자 값을 반올림하는 동작으로 쓰인다고 가정해 보세요. 이 용례를 도형 범주 제목과 합치면 하나의 카탈로그 항목으로 서로 다른 두 문법적 역할을 설명해야 합니다.

Apple에 따르면 현지화 가능한 문자열에는 조회 키가 있으며 테이블에 속합니다. 키는 해당 테이블 안에서 고유해야 합니다. Apple의 Swift 문서에는 기본 원문 값을 유지하면서 별도의 키를 사용하는 방법도 나와 있습니다. 영어 표시 값이 같더라도 의미에 따라 독립적인 번역이 필요하면 별도 키를 사용하세요. 문자열 카탈로그 알아보기, 앱의 텍스트를 번역할 수 있도록 준비하기

실용적인 판단 기준은 하나의 주석으로 모든 용례를 정확히 설명할 수 있는지 확인하는 것입니다. 의미와 UI 역할이 일관되게 유지된다면 맥락을 공유해도 괜찮을 수 있습니다. 설명에 서로 관련 없는 동작을 포함해야 한다면 키 구조를 다시 검토하세요. 이는 모든 컨트롤에 자체 문자열이 필요하다는 규칙이 아니라, Apple의 키 및 테이블 모델에서 도출한 설계상 판단입니다.

레이블을 넘기기 전에 소스 코드 없이 주석을 읽어 보세요. 번역자가 의도한 의미를 파악하고, 인터페이스에서 텍스트가 어디에 쓰이는지 이해하며, 삽입된 콘텐츠가 무엇인지 알 수 있어야 합니다. 레이블의 동작이나 역할이 바뀌면 주석을 수정해 사용자가 보는 인터페이스를 계속 정확히 설명하도록 하세요.

출처