Mac 앱의 모든 현지화 키를 감사하려면 관련 타깃을 빌드하고, 각 문자열 테이블을 지원되는 모든 언어와 대조한 다음, 실행 중인 앱에서 메시지 변형을 테스트합니다. 카탈로그의 완성도와 런타임의 올바른 표시는 각각 따로 확인해야 합니다.

이 워크플로는 Xcode에서 Mac 데스크톱 앱을 유지 관리하는 개발자를 위한 것입니다. 구체적인 목적은 누락된 메시지, 미완성 번역, 잘못된 인수, 표시 문제를 추적할 수 있는 기록을 만드는 것입니다. 예시에 사용된 레이블과 개수는 설명용으로 만든 것이며, 프로젝트에 적용할 수 있는 감사 방법을 보여 줍니다.

완성된 메시지의 기준 정의하기

먼저 간단한 감사 워크시트를 만듭니다. 앱 타깃, 리소스 번들, 문자열 테이블, 키, 지원되는 현지화, 필수 변형, 번역 상태, 런타임 결과를 기록합니다. 번들·테이블·키 조합을 각각 별도의 메시지 식별자로 취급하여, 서로 다른 리소스에서 키 텍스트가 같더라도 누락을 놓치지 않도록 합니다.

Apple은 현지화 가능한 API에서 테이블과 번들을 지정할 수 있으며, 메인 번들 외부의 리소스를 조회하려면 적절한 번들이 필요하다고 설명합니다. 따라서 기본 Localizable.xcstrings 파일만 확인하면 앱의 다른 위치에 있는 메시지를 놓칠 수 있습니다. 앱 텍스트를 번역할 수 있도록 준비하기를 참조하세요.

프로젝트 편집기에서 지원되는 현지화를 확인합니다. Project 아래에서 프로젝트를 선택하고 Info를 연 다음 Localizations를 살펴봅니다. 이 현지화에 포함되는 리소스도 확인합니다. Apple의 언어 및 지역 지원 추가하기에서는 이러한 프로젝트 설정과 리소스 선택을 설명합니다.

워크시트에는 Localization A, Localization B, Localization C 같은 설명용 별칭을 사용할 수 있습니다. 실제 프로젝트 현지화 식별자와의 대응 관계는 작업 기록에 보관하세요. 이 별칭은 워크시트의 레이블이며 Xcode에 입력할 값이 아닙니다.

감사에는 다음 완성 기준을 사용합니다. 이는 Apple이 정의한 완성 상태가 아니라 제안하는 검토 방법입니다.

확인 항목 기록할 근거
인벤토리 메시지의 타깃, 번들, 테이블, 키가 확인되어 있습니다.
검색 메시지를 코드에서 추출했거나 의도적으로 수동 관리합니다.
지원 범위 모든 필수 현지화에 필요한 메시지 변형이 있습니다.
인수 각 인수가 의도한 의미와 호환되는 형식을 유지합니다.
런타임 관련 Mac 인터페이스에 올바른 메시지와 값이 표시됩니다.
처리 상태 각 발견 사항을 수정했거나, 이유를 기록해 의도적으로 제외했거나, 아직 미해결 상태입니다.

번역을 검토하기 전에 카탈로그 인벤토리 만들기

프로젝트에 이미 있는 문자열 카탈로그를 엽니다. 타깃에 카탈로그가 없다면 Apple이 문서화한 생성 경로인 File > New > File from Template을 선택한 다음 String Catalog를 고릅니다. 기본 이름은 Localizable입니다. 코드에서 기대하는 테이블 이름을 사용하세요. Product > Build를 선택해 카탈로그를 채우고 업데이트합니다. 문자열 카탈로그로 텍스트 현지화 및 변형하기를 참조하세요.

성공적인 빌드 한 번을 전체 인벤토리로 간주하지 말고, 관련된 각 Mac 스킴을 빌드합니다. Apple은 추출 과정에서 현재 스킴 및 플랫폼의 문자열을 검색한다고 설명합니다. 한 번의 빌드에서 메시지가 보이지 않더라도 사용되지 않는다고 결론 내리기 전에 확인해야 합니다. 이 범위는 문자열 카탈로그 검색하기에 설명되어 있습니다.

Use Compiler to Extract Swift Strings 빌드 설정을 확인합니다. Apple은 이 설정을 사용해야 현지화 내보내기에 현지화 가능한 Swift 텍스트가 모두 포함된다고 명시합니다. 번역 작업을 위한 교환용 사본이 필요하면 프로젝트를 선택하고 Product > Export Localizations를 선택한 다음 필요한 현지화를 고릅니다. 내보낸 .xcloc 패키지는 개별 .xcstrings 문자열 테이블과는 다른 Xcode 현지화 카탈로그입니다. 현지화 내보내기를 참조하세요.

그런 다음 앱의 일반적인 데스크톱 화면을 차례로 살펴봅니다. 기본 윈도우, 메뉴, 툴바, 설정, 패널, 빈 상태, 개수에 따라 달라지는 레이블을 확인합니다. 앱이 제공하는 메시지를 볼 때마다 워크시트에서 해당 항목을 찾습니다. 표시되는 인터페이스에서 인벤토리로 거꾸로 확인하면 카탈로그에 들어가지 않은 텍스트를 찾는 데 도움이 됩니다.

추출이 임의의 문자열 표현식을 모두 찾아낼 것이라고 가정하지 마세요. Apple은 현지화 가능한 API를 통한 추출을 설명합니다. 예상한 메시지가 없다면 두 번째 항목을 수동으로 추가하기 전에 코드에서 메시지를 어떻게 만들고 전달하는지 살펴봅니다. 앱 텍스트를 번역할 수 있도록 준비하기를 참조하세요.

추출, 조회, 런타임 서식 지정을 구분하기

각 작업이 답하는 질문은 서로 다릅니다. 추출은 Xcode가 개발 중에 메시지를 찾을 수 있는지 확인합니다. 조회는 실행 중인 앱이 어떤 현지화 리소스를 요청하는지 확인합니다. 런타임 서식 지정은 선택된 메시지가 표시할 변수 내용을 제공합니다.

SwiftUI에서는 인수 형식이 중요합니다. Text("Open collection") 같은 리터럴은 현지화 조회에 참여합니다. 해당 이니셜라이저에 일반 String 변수를 전달하면 보통 현지화되지 않은 채 변수 자체가 표시됩니다. Apple은 LocalizedStringKey에서 이 차이를 설명합니다.

변수에서 LocalizedStringKey를 명시적으로 만들면 조회를 요청할 수 있지만, 이것만으로 빌드 시 추출 과정에서 가능한 모든 변수 값을 찾아냈다고 볼 수는 없습니다. 동적으로 선택되는 키가 있다면 허용된 전체 키 집합을 카탈로그와 대조합니다. 테스트 중 우연히 나타난 값에 기대지 말고, 일치하지 않는 모든 값을 조사합니다.

문자열 보간은 메시지 수준에서도 역할을 합니다. SwiftUI는 서식 지정자를 포함한 현지화 메시지를 조회한 뒤 렌더링 전에 보간된 값으로 치환할 수 있습니다. Apple은 Text 설명서에서 현지화 가능한 텍스트를 만들 때 보간을 권장합니다.

항목 개수를 나타내는 설명용 메시지를 생각해 보세요. 카탈로그에는 현지화 가능한 메시지 구조와 변형이 저장되고, 바뀌는 개수는 런타임 동작에 속합니다. 개수가 달라졌다는 이유만으로 1과 24를 각각 독립된 키로 유지할 필요는 없습니다.

그럴듯해 보이는 레이블만으로 조회에 성공했다고 판단하기는 어렵습니다. Apple에 따르면 현지화된 값을 찾을 수 없으면 SwiftUI가 키 자체를 표시할 수 있습니다. 키가 읽을 수 있는 원문 텍스트라면 조회 문제도 평범한 레이블처럼 보일 수 있습니다. 표시 결과와 함께 선택된 현지화 및 카탈로그 항목도 확인하세요. 현지화를 위한 뷰 준비하기를 참조하세요.

모든 언어와 필수 변형 검토하기

한 번에 하나의 테이블과 하나의 현지화를 차례로 검토합니다. 각 메시지에 대해 번역 상태, 텍스트, 인수, 펼쳐지는 변형을 확인합니다. 주변 메시지가 모두 완성되었더라도 미완성 행은 계속 미해결 상태로 둡니다.

Apple의 카탈로그 워크플로에는 New, Needs Review, 번역된 항목, Stale 문자열이 구분되어 있습니다. 오래된 항목은 코드에서 더 이상 발견되지 않은 문자열입니다. 수동 관리 항목은 동기화 중 자동으로 업데이트되거나 제거되지 않습니다. 오래된 키의 번역을 삭제하기 전에 해당 키가 더 이상 필요하지 않은지 확인합니다. 문자열 카탈로그 검색하기를 참조하세요.

개수에 따라 달라지는 메시지의 경우 보간된 키를 Control-클릭하고 Vary by Plural을 선택합니다. Xcode가 각 현지화에 제공하는 모든 형태를 검토합니다. 필요한 형태는 언어마다 다를 수 있으므로 원본 현지화와 행 수가 같은지만 확인해서는 충분하지 않습니다. 카탈로그에 기기별 변형이 있다면 Mac 전용 값과 일반 값을 살펴봅니다. Apple은 문자열 카탈로그로 텍스트 현지화 및 변형하기에서 두 제어 기능을 설명합니다.

인수는 표시 형태뿐 아니라 의미도 확인합니다. 그룹별 항목 수를 나타내는 설명용 메시지라면 어느 인수가 항목 수이고 어느 인수가 그룹 수인지 확인합니다. 번역에 따라 인수 위치는 달라질 수 있지만 그 의미는 유지해야 합니다. Apple의 카탈로그 세션 문자열 카탈로그 검색하기에서는 인수 위치, 형식 지정자, 복수형 치환을 설명합니다.

짧은 레이블이 모호하다면 맥락을 추가합니다. Open에 컬렉션 행에서 실행하는 동작이라는 설명을 붙일 수 있습니다. SwiftUI의 comment 매개변수는 그 맥락을 현지화 출력에 전달합니다. Apple은 현지화를 위한 뷰 준비하기에서 이를 설명합니다.

미완성 작업이 드러나는 지원 범위 매트릭스 사용하기

단일 백분율은 카탈로그 진행 상황을 추적하는 데 유용하지만, 감사에서는 지원 범위와 동작을 별도의 열로 확인해야 합니다. 다음 예시는 그 이유를 보여 줍니다. 숫자는 설명용으로 만든 것이며 앱에서 측정한 값이 아니라 메시지·현지화 쌍을 나타냅니다.

필수 메시지가 48개이고 지원되는 현지화가 세 개라고 가정해 보겠습니다. 그러면 필수 쌍은 144개입니다. 즉, 48에 3을 곱한 값입니다. 각 쌍에는 추가 복수형 또는 기기별 분기가 있을 수 있으며, 이 분기도 별도로 확인해야 합니다.

현지화 필수 쌍 완료된 카탈로그 확인 완료된 런타임 확인
Localization A 48 48 48
Localization B 48 46 44
Localization C 48 48 45
합계 144 142 137

이 예시에서는 카탈로그 작업이 더 필요한 쌍이 두 개이고 런타임 확인을 마치지 않은 쌍이 일곱 개입니다. 두 그룹은 겹칠 수 있으므로 더해서 미완성 메시지의 고유 개수를 구할 수는 없습니다. 각 항목을 실제 해당 행에 기록하세요.

미완성 행마다 구체적인 다음 작업을 기록합니다. 누락된 원본 메시지 찾기, 복수형 분기 완성하기, 인수 확인하기, 번들 선택 조사하기, 더 좁은 너비에서 인터페이스 다시 확인하기 등이 있습니다. 그러면 매트릭스가 보기 좋은 진행 보고서에 그치지 않고 수정 작업 대기열로 기능합니다.

지원되는 모든 현지화에서 Mac 앱 실행하기

반복 가능한 앱 수준 확인을 위해 Xcode의 스킴 설정을 사용합니다. Product > Scheme > Edit Scheme을 선택하고 Run을 선택한 다음 Options를 열어 App Language와 App Region을 고릅니다. 대화상자를 닫고 Mac 실행 대상을 선택한 뒤 앱을 실행합니다. 감사 대상인 지원 조합마다 반복합니다. Apple은 앱 실행 중 현지화 테스트하기에서 이 순서를 설명합니다.

실행할 때마다 같은 경로로 인터페이스를 확인합니다. 빈 컬렉션, 항목 하나, 항목 여러 개, 더 긴 설명용 레이블 등 메시지와 관련된 각 상태를 실행합니다. 복수형 메시지의 경우 해당 현지화에 있는 분기를 실행하는 데 필요한 추가 값을 선택합니다. 고정된 소수의 개수만 테스트해서는 분기를 모두 확인했다고 볼 수 없습니다.

전체 문장, 치환된 값, 줄바꿈, 잘림, 메뉴나 컨트롤의 너비를 살펴봅니다. 메시지에 개수가 두 개 있다면 각각을 독립적으로 바꿉니다. 예를 들어 그룹 수를 일정하게 유지한 채 항목 수를 변경하면 인수 대응 오류를 찾는 데 도움이 됩니다.

SwiftUI 미리보기를 이용하면 수정 주기를 단축할 수 있습니다. Apple은 미리보기의 locale 환경 값을 설정하고, 현지화를 추가하거나 가져온 뒤 여러 현지화 미리보기를 만드는 기능을 지원합니다. 문제가 있는 뷰를 다시 살펴보는 데 미리보기를 활용한 다음 실제 앱 경로에서도 확인하세요. 현지화 미리보기를 참조하세요.

필수 메시지·현지화 쌍마다 처리 상태가 기록되고 필요한 분기까지 확인되면 감사를 마칩니다. 인벤토리, 테스트 경로, 미해결 사항을 함께 보관하세요. 이렇게 기록해 두면 다음 감사에서 변경된 메시지의 위치와 예상 인수, 필수 변형을 알 수 있고 표시 상태도 반복해서 확인할 수 있습니다.

출처