Back to Details

localization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Localization

本地化

Modern iOS localization using String Catalogs (.xcstrings) for managing translations, plural forms, and locale-aware content. Supports SwiftUI's LocalizedStringKey and String(localized:) APIs.
使用String Catalogs（.xcstrings）实现现代iOS本地化，用于管理翻译内容、复数形式和区域适配内容。支持SwiftUI的LocalizedStringKey和String(localized:) API。

Reference Loading Guide

参考资源加载指南

ALWAYS load reference files if there is even a small chance the content may be required. It's better to have the context than to miss a pattern or make a mistake.
ReferenceLoad When
String CatalogsSetting up or using Xcode 15+ String Catalogs
PluralizationHandling plural forms, stringsdict migration
FormattingDate, number, currency locale-aware formatting
RTL SupportRight-to-left layouts, semantic directions
只要有极小可能需要用到相关内容，就务必加载参考文件。 掌握上下文信息总好过遗漏模式或犯错。
参考资源加载时机
String Catalogs设置或使用Xcode 15+ String Catalogs时
Pluralization处理复数形式、stringsdict迁移时
Formatting日期、数字、货币的区域适配格式化时
RTL Support从右到左布局、语义方向设置时

Core Workflow

核心工作流

  1. Create String Catalog in Xcode (File > New > String Catalog)
  2. Mark strings with 
    String(localized:comment:)
    or use SwiftUI's automatic extraction
  3. Add plural variants in String Catalog editor where needed
  4. Test with pseudo-localization (Scheme > Run > Options > App Language)
  5. Export for translation (File > Export Localizations)
  1. 在Xcode中创建String Catalog（文件 > 新建 > String Catalog）
  2. 使用
    String(localized:comment:)
    标记字符串，或利用SwiftUI的自动提取功能
  3. 在需要的地方，在String Catalog编辑器中添加复数变体
  4. 使用伪本地化测试（Scheme > 运行 > 选项 > 应用语言）
  5. 导出用于翻译（文件 > 导出本地化内容）

Key Patterns

核心模式

swift
// SwiftUI - automatic localization
Text("Welcome")
Button("Continue") { }

// Explicit localization with context
let title = String(localized: "Settings", comment: "Navigation title")

// Deferred localization for custom views
struct CardView: View {
    let title: LocalizedStringResource
    var body: some View { Text(title) }
}
swift
// SwiftUI - automatic localization
Text("Welcome")
Button("Continue") { }

// Explicit localization with context
let title = String(localized: "Settings", comment: "Navigation title")

// Deferred localization for custom views
struct CardView: View {
    let title: LocalizedStringResource
    var body: some View { Text(title) }
}

Build Settings

构建设置

  • Use Compiler to Extract Swift Strings: Yes
  • Localization Prefers String Catalogs: Yes
  • 使用编译器提取Swift字符串：是
  • 本地化优先使用String Catalogs：是

Common Mistakes

常见错误

  1. Forgetting String Catalog in Build Phases — Adding String Catalog but forgetting to check "Localize" in File Inspector means it's not embedded. Always verify in Build Phases > Copy Bundle Resources.
  2. Pseudo-localization not tested — Not running your app with pseudo-localization (German/Chinese pseudo-locale) means you miss text overflow and RTL issues. Always test with pseudo-localization before translation.
  3. Hardcoded strings anywhere — Even one hardcoded string outside the String Catalog breaks extraction and automation. Use 
    String(localized:)
    everywhere or use 
    LocalizedStringResource
    for deferred localization.
  4. Context loss in translations — Providing no comment for translators means they guess context and get it wrong. Add comments explaining where the string appears and what it means.
  5. RTL layouts not tested — Assuming LTR layout works for RTL languages (Arabic, Hebrew) fails miserably. Test with system language set to Arabic and verify semantic directions are used.
  1. 忘记在Build Phases中添加String Catalog — 添加了String Catalog但忘记在文件检查器中勾选“本地化”，会导致它不会被嵌入到包中。务必在Build Phases > 复制包资源中进行验证。
  2. 未测试伪本地化 — 不使用伪本地化（德语/中文伪区域）运行应用，会导致遗漏文本溢出和RTL问题。在翻译前务必进行伪本地化测试。
  3. 存在硬编码字符串 — 即使有一个硬编码字符串未放入String Catalog，也会破坏提取和自动化流程。所有地方都要使用
    String(localized:)
    ，或使用
    LocalizedStringResource
    进行延迟本地化。
  4. 翻译时丢失上下文 — 不为翻译人员提供注释，会导致他们猜测上下文并出错。添加注释说明字符串的出现位置和含义。
  5. 未测试RTL布局 — 假设从左到右（LTR）布局适用于RTL语言（阿拉伯语、希伯来语）会导致严重问题。将系统语言设置为阿拉伯语进行测试，并确保使用语义方向。