지역화 및 국제화
String Catalogs를 사용한 앱 지역화에 대한 종합 가이드. Apple Design Award Inclusivity 수상작은 항상 여러 언어를 지원하며 뛰어난 RTL(오른쪽에서 왼쪽) 지원을 제공합니다.
개요
String Catalogs(.xcstrings)는 Xcode 15의 통합된 앱 지역화 관리 형식입니다. 레거시 .strings 및 .stringsdict 파일을 유지 관리, diff, 번역 워크플로우 통합이 더 쉬운 단일 JSON 기반 형식으로 대체합니다.
이 스킬은 String Catalogs, SwiftUI/UIKit 지역화 API, 복수형 처리, RTL 지원, 로케일 인식 포맷팅 및 레거시 형식에서의 마이그레이션 전략을 다룹니다.
이 스킬을 사용해야 하는 경우
- Xcode 15+에서 String Catalog 설정
- SwiftUI 및 UIKit 앱 지역화
- 복수형 올바르게 처리 (많은 언어에 중요)
- RTL 언어 지원 (아랍어, 히브리어)
- 로케일별 날짜, 숫자, 통화 포맷팅
- 레거시
.strings/.stringsdict파일에서 마이그레이션 - App Shortcuts 및 App Intents의 지역화 준비
- 누락된 번역 또는 잘못된 복수형 디버깅
시스템 요구사항
- Xcode 15+: String Catalogs(
.xcstrings)용 - Xcode 26+: 자동 심볼 생성,
#bundle매크로, AI 기반 주석 생성용 - iOS 15+:
LocalizedStringResource용 - iOS 16+: App Shortcuts 지역화용
- 이전 iOS 버전은 레거시
.strings파일 사용
파트 1: String Catalogs (WWDC 2023/10155)
String Catalog 생성
방법 1: Xcode Navigator
- File → New → File
- "String Catalog" 선택
- 이름 지정 (예:
Localizable.xcstrings) - 타겟에 추가
방법 2: 자동 추출
Xcode 15는 다음에서 문자열을 자동으로 추출할 수 있습니다:
- SwiftUI 뷰 (
Text,Label,Button의 문자열 리터럴) - Swift 코드 (
String(localized:)) - Objective-C (
NSLocalizedString) - C (
CFCopyLocalizedString) - Interface Builder 파일 (
.storyboard,.xib) - Info.plist 값
- App Shortcuts 구문
필요한 빌드 설정:
- "Use Compiler to Extract Swift Strings" → Yes
- "Localization Prefers String Catalogs" → Yes
String Catalog 구조
각 항목에는 다음이 포함됩니다:
- Key: 고유 식별자 (기본값: 영어 문자열)
- Default Value: 번역 누락 시 대체값
- Comment: 번역가를 위한 컨텍스트
- String Table: 구성 컨테이너 (기본값: "Localizable")
예시 .xcstrings JSON:
{
"sourceLanguage" : "en",
"strings" : {
"Thanks for shopping with us!" : {
"comment" : "Label above checkout button",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
"value" : "Thanks for shopping with us!"
}
},
"es" : {
"stringUnit" : {
"state" : "translated",
"value" : "¡Gracias por comprar con nosotros!"
}
}
}
}
},
"version" : "1.0"
}
번역 상태
Xcode는 각 번역의 상태를 추적합니다:
- New (⚪) - 문자열이 아직 번역되지 않음
- Needs Review (🟡) - 소스가 변경되어 번역이 오래되었을 수 있음
- Reviewed (✅) - 번역이 승인되고 최신 상태임
- Stale (🔴) - 소스 코드에서 문자열을 더 이상 찾을 수 없음
워크플로우:
- 개발자가 문자열 추가 → New
- 번역가가 번역 추가 → Reviewed
- 개발자가 소스 변경 → Needs Review
- 번역가가 업데이트 → Reviewed
- 개발자가 코드 제거 → Stale
파트 2: SwiftUI 지역화
LocalizedStringKey (자동)
String 매개변수가 있는 SwiftUI 뷰는 자동으로 지역화를 지원합니다:
// ✅ 자동으로 지역화 가능
Text("Welcome to WWDC!")
Label("Thanks for shopping with us!", systemImage: "bag")
Button("Checkout") { }
// Xcode는 이러한 문자열을 String Catalog로 추출합니다
작동 방식: SwiftUI는 내부적으로 LocalizedStringKey를 사용하며, String Catalogs에서 문자열을 조회합니다.
String(localized:)와 주석
Swift 코드에서 명시적 지역화:
// 기본
let title = String(localized: "Welcome to WWDC!")
// 번역가를 위한 주석 포함
let title = String(localized: "Welcome to WWDC!",
comment: "Notification banner title")
// 사용자 정의 테이블 포함
let title = String(localized: "Welcome to WWDC!",
table: "WWDCNotifications",
comment: "Notification banner title")
// 기본값 포함 (키 ≠ 영어 텍스트)
let title = String(localized: "WWDC_NOTIFICATION_TITLE",
defaultValue: "Welcome to WWDC!",
comment: "Notification banner title")
모범 사례: 항상 comment를 포함하여 번역가에게 컨텍스트를 제공하세요.
LocalizedStringResource (지연 지역화)
다른 함수에 지역화 가능한 문자열을 전달할 때:
import Foundation
struct CardView: View {
let title: LocalizedStringResource
let subtitle: LocalizedStringResource
var body: some View {
ZStack {
RoundedRectangle(cornerRadius: 10.0)
VStack {
Text(title) // 렌더링 시 해석됨
Text(subtitle)
}
.padding()
}
}
}
// 사용법
CardView(
title: "Recent Purchases",
subtitle: "Items you've ordered in the past week."
)
주요 차이점: LocalizedStringResource는 사용될 때까지 조회를 지연시켜 사용자 정의 뷰가 완전히 지역화될 수 있도록 합니다.
AttributedString와 Markdown
// Markdown 형식이 지역화에서 유지됩니다
let subtitle = AttributedString(localized: "**Bold** and _italic_ text")
파트 3: UIKit 및 Foundation
NSLocalizedString 매크로
// 기본
let title = NSLocalizedString("Recent Purchases", comment: "Button Title")
// 테이블 포함
let title = NSLocalizedString("Recent Purchases",
tableName: "Shopping",
comment: "Button Title")
// 번들 포함
let title = NSLocalizedString("Recent Purchases",
tableName: nil,
bundle: .main,
value: "",
comment: "Button Title")
Bundle.localizedString
let customBundle = Bundle(for: MyFramework.self)
let text = customBundle.localizedString(forKey: "Welcome",
value: nil,
table: "MyFramework")
사용자 정의 매크로
// Objective-C
#define MyLocalizedString(key, comment) \
[myBundle localizedStringForKey:key value:nil table:nil]
Info.plist 지역화
앱 이름, 권한 등을 지역화:
Info.plist선택- Editor → Add Localization
- 각 언어에 대해
InfoPlist.strings생성:
// InfoPlist.strings (스페인어)
"CFBundleName" = "Mi Aplicación";
"NSCameraUsageDescription" = "La app necesita acceso a la cámara para tomar fotos.";
파트 4: 복수형 처리
언어마다 복수 규칙이 다릅니다:
- 영어: 2가지 형태 (one, other)
- 러시아어: 3가지 형태 (one, few, many)
- 폴란드어: 3가지 형태 (one, few, other)
- 아랍어: 6가지 형태 (zero, one, two, few, many, other)
SwiftUI 복수형 처리
// Xcode가 자동으로 복수형 변형을 생성합니다
Text("\(count) items")
// 사용자 정의 형식 사용
Text("\(visitorCount) Recent Visitors")
String Catalog에서:
{
"strings" : {
"%lld Recent Visitors" : {
"localizations" : {
"en" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Recent Visitor"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%lld Recent Visitors"
}
}
}
}
}
}
}
}
}
XLIFF 내보내기 형식
번역을 위해 내보낼 때 (File → Export Localizations):
레거시 (stringsdict):
<trans-unit id="/%lld Recent Visitors:dict/NSStringLocalizedFormatKey:dict/:string">
<source>%#@recentVisitors@</source>
</trans-unit>
<trans-unit id="/%lld Recent Visitors:dict/recentVisitors:dict/one:dict/:string">
<source>%lld Recent Visitor</source>
<target>%lld Visitante Recente</target>
</trans-unit>
String Catalog (더 깔끔함):
<trans-unit id="%lld Recent Visitors|==|plural.one">
<source>%lld Recent Visitor</source>
<target>%lld Visitante Recente</target>
</trans-unit>
<trans-unit id="%lld Recent Visitors|==|plural.other">
<source>%lld Recent Visitors</source>
<target>%lld Visitantes Recentes</target>
</trans-unit>
복수형 변수와 함께 대체
// 서로 다른 복수형을 가진 여러 변수
let message = String(localized: "\(songCount) songs on \(albumCount) albums")
Xcode는 각 변수의 복수형에 대한 변형을 생성합니다:
songCount: one, otheralbumCount: one, other- 총 조합: 2 × 2 = 4개의 번역 항목
파트 5: 기기 및 너비 변형
기기별 문자열
플랫폼에 따라 다른 텍스트:
// 동일한 코드, 기기별로 다른 문자열
Text("Bird Food Shop")
String Catalog 변형:
{
"Bird Food Shop" : {
"localizations" : {
"en" : {
"variations" : {
"device" : {
"applewatch" : {
"stringUnit" : {
"value" : "Bird Food"
}
},
"other" : {
"stringUnit" : {
"value" : "Bird Food Shop"
}
}
}
}
}
}
}
}
결과:
- iPhone/iPad: "Bird Food Shop"
- Apple Watch: "Bird Food" (작은 화면에 맞게 짧게)
너비 변형
동적 타입 및 크기 클래스:
Text("Application Settings")
String Catalog는 좁은 너비에 대해 더 짧은 텍스트를 제공할 수 있습니다.
파트 6: RTL 지원
레이아웃 미러링
SwiftUI는 RTL 언어에 대해 레이아웃을 자동으로 미러링합니다:
// ✅ 아랍어/히브리어에 대해 자동으로 미러링
HStack {
Image(systemName: "chevron.right")
Text("Next")
}
// iPhone (영어): [>] Next
// iPhone (아랍어): Next [<]
Leading/Trailing vs Left/Right
항상 의미론적 방향 사용:
// ✅ 올바름 - 자동으로 미러링
.padding(.leading, 16)
.frame(maxWidth: .infinity, alignment: .leading)
// ❌ 잘못됨 - 미러링되지 않음
.padding(.left, 16)
.frame(maxWidth: .infinity, alignment: .left)
이미지 및 아이콘
뒤집혀야 하거나 뒤집히지 않아야 하는 이미지 표시:
// ✅ 방향성 있음 - RTL에서 미러링
Image(systemName: "chevron.forward")
// ✅ 방향성 없음 - 절대 미러링되지 않음
Image(systemName: "star.fill")
// 사용자 정의 이미지
Image("backButton")
.flipsForRightToLeftLayoutDirection(true)
RTL 모드 테스트
Xcode Scheme:
- Edit Scheme → Run → Options
- Application Language: Arabic / Hebrew
- 또는: App Language → Right-to-Left Pseudolanguage
시뮬레이터: Settings → General → Language & Region → Preferred Language Order
SwiftUI 프리뷰:
struct ContentView_Previews: PreviewProvider {
static var previews: some View {
ContentView()
.environment(\.layoutDirection, .rightToLeft)
.environment(\.locale, Locale(identifier: "ar"))
}
}
파트 7: 로케일 인식 포맷팅
DateFormatter
let formatter = DateFormatter()
formatter.locale = Locale.current // ✅ 현재 로케일 사용
formatter.dateStyle = .long
formatter.timeStyle = .short
let dateString = formatter.string(from: Date())
// 미국: "January 15, 2024 at 3:30 PM"
// 프랑스: "15 janvier 2024 à 15:30"
// 일본: "2024年1月15日 15:30"
날짜 형식 문자열을 하드코딩하지 마십시오:
// ❌ 잘못됨 - 다른 로케일에서 깨짐
formatter.dateFormat = "MM/dd/yyyy"
// ✅ 올바름 - 로케일에 적응
formatter.dateStyle = .short
NumberFormatter for Currency
let formatter = NumberFormatter()
formatter.locale = Locale.current
formatter.numberStyle = .currency
let priceString = formatter.string(from: 29.99)
// 미국: "$29.99"
// 영국: "£29.99"
// 일본: "¥30" (정수로 반올림)
// 프랑스: "29,99 €" (쉼표 소수점, 기호 앞에 공백)
MeasurementFormatter
let distance = Measurement(value: 100, unit: UnitLength.meters)
let formatter = MeasurementFormatter()
formatter.locale = Locale.current
let distanceString = formatter.string(from: distance)
// 미국: "328 ft" (야드-파운드법으로 변환)
// 미터법 국가: "100 m"
로케일별 정렬
let names = ["Ångström", "Zebra", "Apple"]
// ✅ 로케일 인식 정렬
let sorted = names.sorted { (lhs, rhs) in
lhs.localizedStandardCompare(rhs) == .orderedAscending
}
// 스웨덴: ["Ångström", "Apple", "Zebra"] (스웨덴어에서 Å가 먼저 옴)
// 미국: ["Ångström", "Apple", "Zebra"] (Å를 A로 처리)
파트 8: App Shortcuts 지역화
매개변수가 있는 구문
import AppIntents
struct ShowTopDonutsIntent: AppIntent {
static var title: LocalizedStringResource = "Show Top Donuts"
@Parameter(title: "Timeframe")
var timeframe: Timeframe
static var parameterSummary: some ParameterSummary {
Summary("\(.applicationName) Trends for \(\.$timeframe)") {
\.$timeframe
}
}
}
String Catalog 항목:
- 키:
Show Top Donuts - 키:
\(.applicationName) Trends for \(\.$timeframe)
매개변수 문자열:
// 다양한 통화를 위한 문구 변형
static var sentences: [AppIntentSentence] {
.sentence("Show me my top donuts")
.sentence("What are my best selling donuts?")
.sentence("Show me my top selling donuts for \(\.$timeframe)")
}
각 문장은 String Catalog에서 별도의 항목을 얻습니다.
파트 9: Xcode 26 기능 (현재 베타)
지역화된 리터럴을 위한 자동 심볼 생성
Xcode 26은 String Catalog 항목에 대해 컴파일 타임 타입-세이프 심볼을 생성할 수 있습니다:
// Xcode가 자동으로 생성:
// 🚧 예정: Xcode 26 베타 3에서 작동 예정
extension LocalizedStringResource {
static var welcomeToWWDC: LocalizedStringResource {
"Welcome to WWDC!"
}
static var recentPurchases: LocalizedStringResource {
"Recent Purchases"
}
}
// 사용
Text(.welcomeToWWDC)
활성화 방법:
- String Catalog 선택
- File → Automatic Symbols 활성화
- Xcode가
.swiftinterface파일 생성
#bundle 매크로
// 번들 컨텍스트가 있는 리소스 (Xcode 26+)
let string = String(localized: "Welcome", bundle: #bundle)
// #bundle은 현재 모듈의 번들로 자동 확장됨
// 수동 Bundle.module보다 안전함
AI 기반 번역 주석
Xcode 26은 String Catalog 주석에 AI 생성을 지원합니다:
- String Catalog 열기
- 문자열 항목 선택
- Editor → Generate Comment with AI
- Xcode가 코드 컨텍스트를 분석하여 설명적인 주석을 생성합니다
파트 10: 레거시에서 마이그레이션
자동 마이그레이션 (권장)
- 레거시
.strings또는.stringsdict파일이 있는 프로젝트 열기 - Editor → Migrate to String Catalog 선택
- Xcode가 번역을 새 형식으로 변환
- 변환 검토 및 String Catalog가 타겟에 포함되었는지 확인
수동 마이그레이션
.strings 파일에서:
// Localizable.strings (English)
"welcome_title" = "Welcome to our app!";
"checkout_button" = "Checkout";
String Catalog로:
{
"strings" : {
"welcome_title" : {
"extractionState" : "manual",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
"value" : "Welcome to our app!"
}
}
}
},
"checkout_button" : {
"extractionState" : "manual",
"localizations" : {
"en" : {
"stringUnit" : {
"state" : "translated",
"value" : "Checkout"
}
}
}
}
}
}
.stringsdict 파일에서:
<plist version="1.0">
<dict>
<key>%d items</key>
<dict>
<key>NSStringLocalizedFormatKey</key>
<string>%#@items@</string>
<key>items</key>
<dict>
<key>one</key>
<string>%d item</string>
<key>other</key>
<string>%d items</string>
</dict>
</dict>
</dict>
</plist>
String Catalog 복수형으로:
{
"strings" : {
"%d items" : {
"localizations" : {
"en" : {
"variations" : {
"plural" : {
"one" : {
"stringUnit" : {
"state" : "translated",
"value" : "%d item"
}
},
"other" : {
"stringUnit" : {
"state" : "translated",
"value" : "%d items"
}
}
}
}
}
}
}
}
}
파트 11: String Catalogs 문제 해결
누락된 번역 디버깅
Xcode 16+ Scene 설정:
struct MyApp: App {
var body: some Scene {
WindowGroup {
ContentView()
}
.defaultAppStorage(UserDefaults.standard)
// 누락된 지역화에 대한 콘솔 경고 활성화
}
}
문자열이 추출되지 않는 경우
확인 사항:
- "Use Compiler to Extract Swift Strings"가 활성화되었는지 확인
- 문자열이
Text()또는String(localized:)와 같은 지역화 가능 컨텍스트에 있는지 확인 - Xcode 15+ 프로젝트 형식인지 확인
- 빌드 정리 (Product → Clean Build Folder)
"String not found" 오류
- String Catalog의 키가 코드의 문자열과 일치하는지 확인
- 철자가 동일한지 확인 (공백 및 구두점 포함)
- 서로 다른 String Tables를 사용하는 경우 확인
- Xcode에서 문자열을 수동으로 추가: String Catalog에서 + 버튼
빌드 시 경고
- "Not all strings have translations" → String Catalog에 누락된 번역이 있음
- "String is stale" → 코드에서 제거된 오래된 번역
- "String has duplicate definitions" → 여러 String Catalogs에서 동일한 키
추가 리소스
WWDC 세션
- WWDC 2023: Discover String Catalogs
- WWDC 2024: Internationalization best practices
문서
- [String Catalogs](https://developer.apple.com/documentation/Xcode/localization/
- Internationalization and Localization Guide
관련 기술
핵심 사항
- String Catalogs 사용 (
xcstrings): 현재 및 미래 지향적 접근 방식 - 의미론적 레이아웃 (
leading/trailing): RTL 언어에 필수 - 번역가를 위한 주석 포함: 컨텍스트가 정확한 번역을 보장
- 복수형 올바르게 처리: 언어마다 규칙이 다름
- 로케일 인식 포맷터 사용:
DateFormatter,NumberFormatter,MeasurementFormatter - 왼쪽/오른쪽 사용 금지: 항상 선행/후행 사용
- Xcode 26+ 활용:
#bundle매크로 및 자동 심볼 생성 - 모든 지역화 테스트: Xcode 프리뷰 및 시뮬레이터 사용
- RTL 모드에서 미리보기: 레이아웃 문제 조기 발견
- String Catalogs로 마이그레이션: Xcode의 자동 마이그레이션 도구 사용
이 가이드는 기본적인 지역화 요구사항을 다루며, 앱의 접근성을 확장하고 다양한 언어 사용자를 지원하는 데 도움이 됩니다. 항상 실제 기기나 시뮬레이터에서 최종 사용자 언어로 앱을 테스트하세요.