Xcode에서 String Catalog 키 이름을 바꾸려면 원본 메시지를 별도로 보존하고, 코드 참조를 업데이트한 다음, 기존 번역과 모든 변형을 확인하세요. 추출된 문자열의 경우 Xcode 26에서 변환 리팩터링을 사용할 수 있으며, 조회 키만 변경하는 것으로는 충분하지 않습니다.

이 가이드는 기존 .xcstrings 카탈로그를 사용하는 SwiftUI Mac 앱을 유지 관리하는 사람을 위한 것입니다. 목표는 화면에 표시되는 문구와 번역을 그대로 유지하면서 문장 형태의 키를 의미 있는 식별자로 바꾸는 것입니다. Apple은 아래 API와 변환 작업 흐름을 문서화하지만, 임의로 키를 수정해도 모든 번역이 자동으로 이전된다고 보장하지는 않습니다.

키를 변경할 때 무엇을 그대로 유지해야 하나요?

지역화 가능한 메시지에는 식별자 외에도 여러 요소가 있습니다. Apple은 키, 기본값, 주석, 문자열 테이블을 서로 별개의 구성 요소로 설명합니다. 키는 런타임에 메시지를 식별하고, 기본값은 원본 문구를 제공합니다. 카탈로그에는 테이블의 번역과 메타데이터가 저장됩니다. 이름 변경은 해당 메시지 계약을 구성하는 요소를 함께 변경하는 작업으로 다루세요. String Catalog 살펴보기

수정하기 전에 영향을 받는 항목마다 다음 내용을 기록하세요. 아래의 예시는 이름 변경을 보여 주는 가상의 사례이며, 측정 결과가 아닙니다.

구성 요소 변경 전 의도한 결과
조회 키 Open collection collection.open
원본 메시지 Open collection 변경 없음
테이블 Localizable 변경 없음
번들 메인 앱 번들 변경 없음
번역자용 문맥 선택한 컬렉션을 여는 버튼 보존
기존 번역 모든 지역화의 현재 값 보존
개수 인수(있는 경우) 정수 개수 같은 형식과 의미
복수형 또는 기기별 변형 기존 분기 보존

이 기록을 비교 자료로 사용하세요. 빌드가 성공했다고 해서 번역이 보존되었다고 단정할 수는 없습니다. 조회에 실패해도 앱이 기본 메시지를 표시할 수 있기 때문입니다. SwiftUI 문서에 따르면 카탈로그에서 일치하는 항목을 찾지 못하면 지역화 키가 그대로 표시될 수 있습니다. 의미를 담은 키를 사용하면 인터페이스에 collection.open 같은 식별자가 노출될 수 있습니다. 지역화를 위한 뷰 준비하기

카탈로그를 수정하기 전에 원본 찾기

Xcode의 프로젝트 탐색기에서 기존 카탈로그를 여세요. Editor > Assistant를 선택한 다음 항목을 선택해 원본을 확인하세요. Apple은 키 옆의 화살표와 Attributes 검사기에 표시되는 예시 사용처를 참조를 찾는 방법으로도 안내합니다. 추출된 문자열의 경우 소스 변경 후 Product > Build를 선택해 카탈로그를 동기화하세요. 문자열 카탈로그로 텍스트 지역화 및 변형하기

항목이 코드에서 추출되었는지, 수동으로 관리되는지 확인하세요. Apple에 따르면 추출된 메시지는 소스 코드가 관리하며, 빌드할 때 소스 값이 동기화됩니다. 번역된 항목이 추출 대상에서 사라지면 Stale로 남고, 번역되지 않은 항목은 삭제될 수 있습니다. 수동 관리 항목은 추출 과정에서 업데이트되거나 삭제되지 않습니다. 따라서 대체 항목이 나타났다는 이유만으로 이전 번역 항목을 삭제하지 마세요. String Catalog 살펴보기

진행하기 전에 복구할 수 있는 체크포인트를 만들고, 작업 후 영향을 받는 항목을 체크포인트와 비교하세요. 번역이 누락된 원인을 좁힐 수 있도록 이 작업 중에는 테이블과 번들을 그대로 유지하세요. Apple의 지역화 API에서 테이블과 번들 정보를 받는 이유는 이 값들이 메시지를 찾을 위치를 결정하기 때문입니다. 앱의 텍스트를 번역에 맞게 준비하기

추출된 문자열에는 Xcode의 변환 리팩터링 사용하기

Xcode 26 이상을 사용하는 프로젝트라면 기존에 추출된 항목을 생성된 지역화 기호로 변환하는 방법을 고려하세요. Apple은 Xcode 26에서 이 작업 흐름을 도입했으며, 변환 중 키를 의미 있는 이름으로 바꾸는 방법을 보여 줍니다. 메시지를 식별하고 참조하는 방식을 함께 바꾸는 문서화된 방법입니다. 코드 따라 하기: Xcode로 지역화 살펴보기

  1. 기존 프로젝트에서 필요한 경우 빌드 설정의 Generate String Catalog Symbols가 Yes로 설정되어 있는지 확인합니다.
  2. 카탈로그 편집기에서 기존 키를 선택하고 Control 키를 누른 채 클릭한 다음 Refactor > Convert Strings to Symbols를 선택합니다.
  3. 카탈로그 키 변경 사항과 영향을 받는 소스 위치를 보여 주는 미리보기를 확인합니다.
  4. 변환 인터페이스에서 제안된 의미 있는 이름과 해당하는 경우 인수 이름을 수정합니다.
  5. 강조 표시된 미리보기에서 현재 코드와 수정된 코드를 비교한 다음 Convert를 클릭합니다.
  6. 빌드한 뒤 번역과 변형을 포함해 결과 항목을 체크포인트와 비교합니다.

Apple은 이러한 변환 제어 기능을 문서화하고 Attributes 검사기에 생성된 사용 예시를 보여 줍니다. 원하는 카탈로그 키의 문장 부호를 보고 Swift 식별자를 추측하지 말고, 해당 예시를 사용하세요. 생성된 기호는 카탈로그 정보에 따라 달라지며, 기본 테이블이 아닌 테이블은 테이블 네임스페이스를 사용합니다. 코드에서 생성된 지역화 기호 사용하기

이 리팩터링은 추출된 문자열을 생성된 기호로 전환하는 작업입니다. 인용된 문서에는 모든 수동 관리 항목이나 외부 참조에 적용되는 보편적인 이름 변경 작업이 설명되어 있지 않습니다. 미리보기에 필요한 참조가 표시되지 않으면 이전 키를 제거하기 전에 해당 참조를 명시적으로 처리하세요.

코드에서 키와 기본값을 관리하려면 추출 유지하기

코드에서 추출하는 방식을 유지할 수도 있습니다. Apple은 String(localized:defaultValue:...)를 통해 조회 키와 원본 메시지를 분리하는 방법을 명시적으로 지원합니다. 첫 번째 인수는 키를 제공하고, defaultValue은 원본 문자열을 제공합니다. 예를 들어 의미를 담은 키를 사용하면서 기본 메시지로 Open collection을 유지할 수 있습니다. 앱의 텍스트를 번역에 맞게 준비하기

다음은 정적 레이블 하나와 정수 개수 하나에 이 패턴을 적용한 완전한 앱 소스 예시입니다. 배포 대상이 macOS 12 이상인 macOS SwiftUI 앱 타깃을 사용하고, 두 번째 @main 선언을 추가하는 대신 기존 앱 진입점 소스를 교체하세요. 앱 타깃에 Localizable.xcstrings를 추가합니다. 이 예시는 Apple API를 기준으로 검토했지만, Swift 툴체인을 사용할 수 없어 여기서 컴파일하지는 않았습니다.

import Foundation
import SwiftUI

@main
struct CatalogRenameDemoApp: App {
    var body: some Scene {
        WindowGroup {
            CatalogRenameDemoView()
        }
    }
}

struct CatalogRenameDemoView: View {
    private let itemCount: Int = 7

    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            Text(verbatim: String(
                localized: "collection.open",
                defaultValue: "Open collection",
                comment: "Label for opening the selected collection."
            ))

            Text(verbatim: String(
                localized: "collection.itemCount",
                defaultValue: "\(itemCount) items",
                comment: "Number of items in the selected collection."
            ))
        }
        .padding()
    }
}

여기서 String(localized:...)은 결과 문자열이 표시되기 전에 지역화된 텍스트를 가져옵니다. Text(verbatim:)은 이 표시 단계를 명시적으로 나타냅니다. Apple은 즉시 문자열을 지역화하는 방식과 조회를 지연할 수 있는 LocalizedStringResource를 구분합니다. 뷰 사이에 미해결 메시지를 전달하는 재사용 가능한 인터페이스에는 LocalizedStringResource 같은 지역화 가능한 형식을 권장합니다. LocalizedStringResource, 앱의 텍스트를 번역에 맞게 준비하기

이 방식으로 기존 메시지를 이전할 때는 빌드해 대상 항목을 만들거나 업데이트한 다음, 이전 항목을 삭제하기 전에 기존 번역을 옮기세요. Apple은 지역화를 선택하고 해당 언어 열을 수정해 번역을 직접 입력하는 방법을 안내합니다. 변형 메시지의 경우 최상위 텍스트만 복사하지 말고 해당하는 모든 분기를 보존하세요. 단계별 이전은 문서화된 편집 도구를 바탕으로 한 실용적인 절차이며, 자동 이름 변경이 보장되는 것은 아닙니다. 문자열 카탈로그로 텍스트 지역화 및 변형하기

추출과 런타임 서식 지정은 어떻게 다른가요?

추출은 개발 중에 이루어집니다. Xcode가 지원되는 지역화 표현식을 찾아 카탈로그를 업데이트합니다. 런타임 서식 지정은 앱이 메시지를 확인하고 값을 삽입할 때 이루어집니다. 예시의 개수 7은 런타임 인수이므로 안정적인 키의 일부로 만들면 안 됩니다.

정수 삽입을 지역화 표현식 안에 유지하세요. Apple의 String.LocalizationValue는 삽입을 지원하며, 임의의 식별자를 사용하려는 개발자에게는 정적 키와 별도의 defaultValue를 받는 이니셜라이저를 안내합니다. 먼저 일반 렌더링 문자열을 구성하는 방식은 지역화 가능한 메시지와 그 인수를 보존하는 것과 같지 않습니다. String.LocalizationValue

문법에 맞는 개수 메시지를 만들려면 추출된 개수 항목을 선택하고 Control 키를 누른 채 클릭한 다음 Vary by Plural을 선택하세요. 원본 변형과 각 기존 지역화에 필요한 변형을 모두 작성합니다. 영어 원본의 경우 Apple은 One에 %lld item, Other에 %lld items를 사용하는 예시를 보여 줍니다. 삽입을 추가하는 것만으로 이러한 변형이 완성되지는 않습니다. 문자열 카탈로그로 텍스트 지역화 및 변형하기

이름을 바꾸는 동안 인수의 형식, 위치, 의미를 보존하세요. 이전 메시지에 정수 개수가 있었다면 이를 미리 서식이 적용된 문자열로 바꾸는 것은 서식 지정 계약도 바꾸는 일입니다. 생성된 기호의 경우 형식 지정자가 있는 메시지에는 Xcode가 형식이 지정된 매개변수를 가진 함수를 생성하므로, 변환할 때 해당 시그니처를 확인하세요. 코드에서 생성된 지역화 기호 사용하기

이전 항목을 제거하기 전에 보존 여부 확인하기

완료 여부를 확인할 때 다음 항목을 점검하세요. 이 점검을 통해 카탈로그 문제와 조회 또는 서식 지정 문제를 구분할 수 있습니다.

점검 항목 기대 결과 실패 시 확인할 사항
원본 문구 체크포인트와 일치 기본값 누락 또는 변경
기존 번역 이전 값이 모두 새 키 아래에서 사용 가능 이전 누락 또는 잘못된 대상
변형 구조 이전의 모든 복수형 및 기기별 분기가 유지됨 최상위 값만 복사됨
런타임 레이블 의도한 메시지가 표시됨 키, 테이블, 번들 또는 지역화 불일치
가상 개수 0, 1, 7 값이 올바르게 삽입되고 필요한 복수형 분기가 작동함 인수 또는 변형 불일치
이전 참조 필요한 사용처가 남아 있지 않음 이전 누락

기존 지역화에서 Mac 앱을 테스트하려면 Product > Scheme > Edit Scheme을 선택하고 Run을 선택한 다음 Options를 열어 App Language를 선택하세요. 대화상자를 닫고 Mac 대상을 실행합니다. 이름 변경의 영향을 받은 지역화를 각각 테스트하며 실제 레이블과 개수 메시지를 확인하세요. Apple은 이 스킴 기반 테스트 작업 흐름을 문서화합니다. 앱 실행 중 지역화 테스트하기

새 키가 나타나지만 번역이 비어 있으면 이전 항목으로 돌아가 누락된 내용을 옮기세요. 화면에 식별자가 나타나면 조회 입력값을 확인하세요. 개수만 올바르게 표시되지 않으면 삽입과 변형을 확인하세요. 내용을 처리하고 필요한 참조를 이전한 뒤에 이전 항목을 제거합니다. 완료된 변경은 식별자를 바꾸면서 메시지, 인수, 독자에게 이미 표시되던 번역을 보존해야 합니다.

출처