현지화 및 국제화(i18n)
String Catalog를 사용한 앱 현지화에 대한 포괄적인 가이드입니다. Apple Design Award Inclusivity 수상작들은 항상 뛰어난 RTL(오른쪽에서 왼쪽) 지원과 함께 여러 언어를 지원합니다.
개요
String Catalog(.xcstrings)는 Xcode 15에서 도입된 앱 현지화 관리를 위한 통합 형식입니다. 레거시 .strings 및 .stringsdict 파일을 대체하는 단일 JSON 기반 형식으로, 유지보수, diff, 번역 워크플로우 통합이 더 쉽습니다.
이 스킬은 String Catalog, SwiftUI/UIKit 현지화 API, 복수형 처리, RTL 지원, 로케일 인식 형식 지정, 레거시 형식에서의 마이그레이션 전략을 다룹니다.
이 스킬을 사용해야 할 때
- Xcode 15+에서 String Catalog 설정
- SwiftUI 및 UIKit 앱 현지화
- 복수형 올바르게 처리 (많은 언어에서 중요)
- RTL 언어 지원 (아랍어, 히브리어)
- 로케일별 날짜, 숫자, 통화 형식 지정
- 레거시
.strings/.stringsdict파일에서 마이그레이션 - App Shortcuts 및 App Intents 현지화 준비
- 누락된 번역 또는 잘못된 복수형 디버깅
시스템 요구 사항
- Xcode 15+: String Catalog(
.xcstrings)용 - Xcode 26+: 자동 심볼 생성,
#bundle매크로, AI 기반 주석 생성용 - iOS 15+:
LocalizedStringResource용 - iOS 16+: App Shortcuts 현지화용
- 이전 iOS 버전은 레거시
.strings파일 사용
1부: String Catalog (WWDC 2023/10155)
String Catalog 생성
방법 1: Xcode 네비게이터
- 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 Catalog에서 문자열을 조회합니다.
주석이 있는 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는 조회를 사용 시점까지 지연시켜 사용자 정의 뷰를 완전히 현지화할 수 있게 합니다.
Markdown이 포함된 AttributedString
// 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
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가 자동으로 추출하는 항목:
- Intent 제목
- 매개변수 이름
- 플레이스홀더가 포함된 구문 템플릿
현지화된 구문:
영어: "Food Truck Trends for this week"
스페인어: "Tendencias de Food Truck para esta semana"
AppShortcutsProvider 현지화
struct FoodTruckShortcuts: AppShortcutsProvider {
static var appShortcuts: [AppShortcut] {
AppShortcut(
intent: ShowTopDonutsIntent(),
phrases: [
"\(.applicationName) Trends for \(\.$timeframe)",
"Show trending \(\.$timeframe) donuts",
"Trending donuts for \(\.$timeframe)",
],
shortTitle: "Donut Trends",
systemImageName: "chart.bar"
)
}
}
String Catalog는 각 구문에 대한 항목을 자동으로 생성하며 번역가가 현지화할 수 있습니다.
9부: 고급 String Catalog 기능
댓글 자동 생성 (Xcode 26+)
Xcode 26+는 AI를 사용하여 자동으로 댓글을 생성합니다:
// Xcode가 소스 코드 컨텍스트를 분석하여 스마트 댓글을 생성
Button("Submit Order") { }
// 자동 댓글:
// "결제 화면 하단에 있는 장바구니 최종 확인 버튼"
Xcode 26+ 심볼 생성
자동 생성된 Swift 구조체:
// String Catalog에 정의된 문자열에 대한 타입 안전 심볼
Label(localized: .myApp.welcomeMessage)
Text(.localizable.thanksForShopping)
#bundle 매크로: 컴파일 타임에 번들 첨부:
// 명시적 번들 참조가 필요 없음
let footer = String(localized: "Privacy Policy", bundle: #bundle(from: MyView.self))
String Catalog와 Swift Testing
현지화된 출력이 예상과 일치하는지 확인:
@Test func localizedStringsAreCorrect() {
let english = String(localized: "Welcome",
locale: Locale(identifier: "en"))
let french = String(localized: "Welcome",
locale: Locale(identifier: "fr"))
#expect(english == "Welcome")
#expect(french == "Bienvenue")
}
10부: 모범 사례 및 패턴
하는 것
- 항상 댓글을 포함하세요 - 컨텍스트를 제공합니다
- 의미론적 레이아웃 방향을 사용하세요 -
leading/trailing,left/right를 사용하지 마세요 - 복수형을 올바르게 처리하세요 - String Catalog 변형을 사용하세요
- 로케일 인식 포맷터를 사용하세요 -
DateFormatter,NumberFormatter - String Catalog 변형을 활용하세요 - 기기, 너비, 복수형
- 외부화 가능한 키를 사용하세요 - 키는 영어 텍스트일 필요가 없습니다
- App Intents를 철저히 현지화하세요 - 사용자는 해당 언어로 Siri와 상호작용합니다
- RTL을 테스트하세요 - 시뮬레이터와 미리보기에서 모두 테스트
하지 말아야 할 것
- 날짜 형식을 하드코딩하지 마세요 -
dateStyle/timeStyle을 사용하세요 - 문자열 연결을 사용하지 마세요 -
String(localized:)를 사용하거나 형식 지정자를 사용하세요 - 번역을 건너뛰지 마세요 - 사용자에게 누락된 문자열은 프로페셔널하지 않게 보입니다
- RTL 이미지를 무시하지 마세요 - 항상 방향성을 염두에 두세요
- iOS 15 이하를 대상으로 하는 경우 LocalizedStringResource를 사용하지 마세요 - 대신
Text또는NSLocalizedString을 사용하세요
성능 팁
- String Catalog는 효율적입니다 - 레거시
.strings파일보다 성능이 뛰어납니다 - 지연 로딩 - 자주 사용하지 않는 언어의 경우 번들을 지연 로드하세요
- 프리페칭 - 앱 시작 시 자주 사용되는 문자열을 캐시하세요