Communitygithub.com

지역화 및 국제화 (Localization & Internationalization)

앱 지역화, String Catalog 사용, 타입-세이프 심볼 생성 (Xcode 26+), 복수형 처리, RTL 레이아웃, 로케일 인식 포맷팅, .strings 파일 마이그레이션 등 Xcode 15-26을 위한 종합적인 i18n 패턴을 제공합니다.

지역화 및 국제화 (Localization & Internationalization)란 무엇인가요?

이 스킬은 Apple 플랫폼에서 앱을 지역화하고 국제화하는 방법에 대한 포괄적인 가이드입니다. Xcode 15의 String Catalog(.xcstrings)를 사용하여 레거시 .strings 및 .stringsdict 파일을 대체하고, SwiftUI 및 UIKit 앱의 지역화를 설정하는 방법을 다룹니다. 또한 복수형 처리(다양한 언어의 복수 규칙), RTL(오른쪽에서 왼쪽) 레이아웃 지원, 로케일 인식 날짜/숫자/통화 포맷팅, App Shortcuts 지역화 등 실질적인 패턴을 제공합니다. Xcode 16 이상의 새로운 기능(자동 심볼 생성, #bundle 매크로, AI 기반 주석 생성)도 포함되어 있어, 현대적인 Apple 앱 개발에서 지역화 모범 사례를 적용하고자 하는 모든 개발자에게 유용합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/Axiom/.claude-plugin/plugins/axiom/skills/localization

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

지역화 및 국제화

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

  1. File → New → File
  2. "String Catalog" 선택
  3. 이름 지정 (예: Localizable.xcstrings)
  4. 타겟에 추가

방법 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 (🔴) - 소스 코드에서 문자열을 더 이상 찾을 수 없음

워크플로우:

  1. 개발자가 문자열 추가 → New
  2. 번역가가 번역 추가 → Reviewed
  3. 개발자가 소스 변경 → Needs Review
  4. 번역가가 업데이트 → Reviewed
  5. 개발자가 코드 제거 → 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 지역화

앱 이름, 권한 등을 지역화:

  1. Info.plist 선택
  2. Editor → Add Localization
  3. 각 언어에 대해 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, other
  • albumCount: 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:

  1. Edit Scheme → Run → Options
  2. Application Language: Arabic / Hebrew
  3. 또는: 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)

활성화 방법:

  1. String Catalog 선택
  2. File → Automatic Symbols 활성화
  3. Xcode가 .swiftinterface 파일 생성

#bundle 매크로

// 번들 컨텍스트가 있는 리소스 (Xcode 26+)
let string = String(localized: "Welcome", bundle: #bundle)

// #bundle은 현재 모듈의 번들로 자동 확장됨
// 수동 Bundle.module보다 안전함

AI 기반 번역 주석

Xcode 26은 String Catalog 주석에 AI 생성을 지원합니다:

  1. String Catalog 열기
  2. 문자열 항목 선택
  3. Editor → Generate Comment with AI
  4. Xcode가 코드 컨텍스트를 분석하여 설명적인 주석을 생성합니다

파트 10: 레거시에서 마이그레이션

자동 마이그레이션 (권장)

  1. 레거시 .strings 또는 .stringsdict 파일이 있는 프로젝트 열기
  2. Editor → Migrate to String Catalog 선택
  3. Xcode가 번역을 새 형식으로 변환
  4. 변환 검토 및 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" 오류

  1. String Catalog의 키가 코드의 문자열과 일치하는지 확인
  2. 철자가 동일한지 확인 (공백 및 구두점 포함)
  3. 서로 다른 String Tables를 사용하는 경우 확인
  4. Xcode에서 문자열을 수동으로 추가: String Catalog에서 + 버튼

빌드 시 경고

  • "Not all strings have translations" → String Catalog에 누락된 번역이 있음
  • "String is stale" → 코드에서 제거된 오래된 번역
  • "String has duplicate definitions" → 여러 String Catalogs에서 동일한 키

추가 리소스

WWDC 세션

문서

관련 기술


핵심 사항

  1. String Catalogs 사용 (xcstrings): 현재 및 미래 지향적 접근 방식
  2. 의미론적 레이아웃 (leading/trailing): RTL 언어에 필수
  3. 번역가를 위한 주석 포함: 컨텍스트가 정확한 번역을 보장
  4. 복수형 올바르게 처리: 언어마다 규칙이 다름
  5. 로케일 인식 포맷터 사용: DateFormatter, NumberFormatter, MeasurementFormatter
  6. 왼쪽/오른쪽 사용 금지: 항상 선행/후행 사용
  7. Xcode 26+ 활용: #bundle 매크로 및 자동 심볼 생성
  8. 모든 지역화 테스트: Xcode 프리뷰 및 시뮬레이터 사용
  9. RTL 모드에서 미리보기: 레이아웃 문제 조기 발견
  10. String Catalogs로 마이그레이션: Xcode의 자동 마이그레이션 도구 사용

이 가이드는 기본적인 지역화 요구사항을 다루며, 앱의 접근성을 확장하고 다양한 언어 사용자를 지원하는 데 도움이 됩니다. 항상 실제 기기나 시뮬레이터에서 최종 사용자 언어로 앱을 테스트하세요.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

관련 스킬