第 1 部分：字符串目录 (WWDC 2023/10155)

创建字符串目录

方法 1：Xcode 导航器

1. 文件 → 新建 → 文件
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" → 是
• "Localization Prefers String Catalogs" → 是

字符串目录结构

每个条目包含：

• 键：唯一标识符（默认：英文字符串）
• 默认值：翻译缺失时的回退值
• 注释：为翻译人员提供的上下文
• 字符串表：组织容器（默认："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 跟踪每个翻译的状态：

• 新建 (⚪) - 字符串尚未翻译
• 需要审核 (🟡) - 源字符串已更改，翻译可能已过时
• 已审核 (✅) - 翻译已批准且为最新
• 陈旧 (🔴) - 源代码中不再找到该字符串

工作流程：

1. 开发者添加字符串 → 新建
2. 翻译人员添加翻译 → 已审核
3. 开发者更改源字符串 → 需要审核
4. 翻译人员更新 → 已审核
5. 开发者移除代码 → 陈旧

第 2 部分：SwiftUI 本地化

LocalizedStringKey（自动）

带有 String 参数的 SwiftUI 视图自动支持本地化：

// ✅ 自动可本地化
Text("Welcome to WWDC!")
Label("Thanks for shopping with us!", systemImage: "bag")
Button("Checkout") { }

// Xcode 将这些字符串提取到字符串目录

工作原理：SwiftUI 内部使用 LocalizedStringKey，它在字符串目录中查找字符串。

带注释的 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 本地化

本地化应用名称、权限等：

1. 选择 Info.plist
2. 编辑器 → 添加本地化
3. 为每种语言创建 InfoPlist.strings：

// InfoPlist.strings（西班牙语）

"CFBundleName" = "Mi Aplicación";
"NSCameraUsageDescription" = "La app necesita acceso a la cámara para tomar fotos.";

第 4 部分：复数化

不同语言有不同的复数规则：

• 英语：2 种形式（单数、复数）
• 俄语：3 种形式（单数、少数、多数）
• 波兰语：3 种形式（单数、少数、复数）
• 阿拉伯语：6 种形式（零、单数、双数、少数、多数、复数）

SwiftUI 复数处理

// Xcode 自动创建复数变体
Text("\(count) items")

// 使用自定义格式
Text("\(visitorCount) Recent Visitors")

在字符串目录中：

{
  "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 导出格式

导出以供翻译时（文件 → 导出本地化）：

传统（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 state="new">%lld Visitante Recente</target>
</trans-unit>

字符串目录（更简洁）：

<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：单数、复数
• albumCount：单数、复数
• 总组合数：2 × 2 = 4 个翻译条目

第 5 部分：设备和宽度变体

设备特定字符串

不同平台使用不同的文本：

// 相同代码，不同设备使用不同字符串
Text("Bird Food Shop")

字符串目录变体：

{
  "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")

字符串目录可以为窄宽度提供更短的文本。

第 6 部分：RTL 支持

布局镜像

SwiftUI 自动为 RTL 语言镜像布局：

// ✅ 自动为阿拉伯语/希伯来语镜像
HStack {
    Image(systemName: "chevron.right")
    Text("Next")
}

// iPhone（英语）：[>] Next
// iPhone（阿拉伯语）：Next [<]

Leading/Trailing 与 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 方案：

1. 编辑方案 → 运行 → 选项
2. 应用语言：阿拉伯语 / 希伯来语
3. 或：应用语言 → 从右到左伪语言

模拟器：设置 → 通用 → 语言与地区 → 首选语言顺序

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
        }
    }
}

字符串目录自动提取：

• 意图标题
• 参数名称
• 带占位符的短语模板

本地化短语：

英语："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 donuts for \(\.$timeframe) in \(.applicationName)",
                "Give me trends for \(\.$timeframe) in \(.applicationName)"
            ]
        )
    }
}

Xcode 将所有 3 个短语提取到字符串目录中进行翻译。

第 9 部分：从传统格式迁移

将 .strings 转换为 .xcstrings

自动迁移：

1. 在导航器中选择 .strings 文件
2. 编辑器 → 转换为字符串目录
3. Xcode 创建 .xcstrings 并保留翻译

手动方法：

1. 创建新的字符串目录
2. 构建项目（Xcode 从代码中提取字符串）
3. 通过文件 → 导入本地化（XLIFF）导入翻译
4. 删除旧的 .strings 文件

转换 .stringsdict

复数文件自动合并：

1. 将 .strings 和 .stringsdict 放在一起
2. 转换 → 两者合并为单个 .xcstrings
3. 保留复数变体

渐进式迁移策略

阶段 1：新代码使用字符串目录

• 创建 Localizable.xcstrings
• 使用 String(localized:) 编写新代码
• 为旧代码保留传统的 .strings 文件

阶段 2：迁移现有字符串

• 一次转换一个 .strings 表
• 每次转换后测试翻译
• 更新使用旧 NSLocalizedString 调用的代码

阶段 3：删除传统文件

• 删除 .strings 和 .stringsdict 文件
• 验证字符串目录中的所有字符串
• 提交到 App Store

共存：.strings 和 .xcstrings 可以一起工作 - Xcode 会同时检查两者。

常见错误

硬编码字符串

// ❌ 错误 - 不可本地化
Text("Welcome")
let title = "Settings"

// ✅ 正确 - 可本地化
Text("Welcome")  // SwiftUI 自动本地化
let title = String(localized: "Settings")

拼接本地化字符串

// ❌ 错误 - 词序因语言而异
let message = String(localized: "You have") + " \(count) " + String(localized: "items")

// ✅ 正确 - 带替换的单个可本地化字符串
let message = String(localized: "You have \(count) items")

为何错误：有些语言将数字放在名词前，有些放在后。

缺少复数形式

// ❌ 错误 - 对许多语言语法不正确
Text("\(count) item(s)")

// ✅ 正确 - 正确的复数处理
Text("\(count) items")  // Xcode 创建复数变体

忽略 RTL

// ❌ 错误 - 在 RTL 语言中会出错
.padding(.left, 20)
HStack {
    backButton
    Spacer()
    title
}

// ✅ 正确 - 自动镜像
.padding(.leading, 20)
HStack {
    backButton  // 在 RTL 中出现在右侧
    Spacer()
    title
}

错误的日期/数字格式

// ❌ 错误 - 仅限美国格式
let formatter = DateFormatter()
formatter.dateFormat = "MM/dd/yyyy"

// ✅ 正确 - 适应区域设置
formatter.dateStyle = .short
formatter.locale = Locale.current

忘记注释

// ❌ 错误 - 翻译人员没有上下文
String(localized: "Confirm")

// ✅ 正确 - 清晰的上下文
String(localized: "Confirm", comment: "Button to confirm delete action")

影响："Confirm" 可能意味着 "verify" 或 "acknowledge" - 上下文对于准确翻译很重要。

故障排除

字符串未出现在字符串目录中

原因：构建设置未启用

解决方案：

1. 构建设置 → "Use Compiler to Extract Swift Strings" → 是
2. 清理构建文件夹 (Cmd+Shift+K)
3. 构建项目

翻译未在应用中显示

原因 1：语言未添加到项目

1. 项目 → 信息 → 本地化 → + 按钮
2. 添加目标语言

原因 2：字符串标记为 "陈旧"

• 删除陈旧字符串或验证代码仍在使用它们

复数形式不正确

原因：使用 String.localizedStringWithFormat 而不是字符串目录

解决方案：使用字符串目录的自动复数处理：

// ✅ 正确
Text("\(count) items")

// ❌ 错误
Text(String.localizedStringWithFormat(NSLocalizedString("%d items", comment: ""), count))

XLIFF 导出缺少字符串

原因："Localization Prefers String Catalogs" 未设置

解决方案：

1. 构建设置 → "Localization Prefers String Catalogs" → 是
2. 再次导出本地化

生成的符号未出现（Xcode 26+）

原因 1：构建设置未启用

解决方案：

1. 构建设置 → "Generate String Catalog Symbols" → 是
2. 清理构建文件夹 (Cmd+Shift+K)
3. 重新构建项目

原因 2：字符串未手动添加到目录

解决方案：符号仅针对手动添加的字符串生成（字符串目录中的 + 按钮）。自动提取的字符串不生成符号。

#bundle 宏不工作（Xcode 26+）

原因：语法错误或缺少导入

解决方案：

import Foundation  // #bundle 必需
Text("My Collections", bundle: #bundle, comment: "Section title")

验证使用的是 #bundle 而不是 .module。

重构为符号失败（Xcode 26+）

原因 1：字符串不在字符串目录中

1. 确保字符串存在于 .xcstrings 文件中
2. 构建项目以刷新目录
3. 再次尝试重构

原因 2：构建设置未启用

• 在构建设置中启用 "Generate String Catalog Symbols"
• 清理并重新构建

第 10 部分：Xcode 26 本地化增强功能

Xcode 26 引入了类型安全的本地化与生成的符号、使用设备端 AI 的自动注释生成，以及通过 #bundle 宏改进的 Swift Package 支持。基于 WWDC 2025 第 225 场会议 "Explore localization with Xcode"。

生成的符号（类型安全本地化）

问题：基于字符串的本地化在出现拼写错误时会静默失败。

// ❌ 拼写错误 - 在运行时静默失败
Text("App.HomeScren.Title")  // Screen 中缺少 'e'

解决方案：Xcode 26 从手动添加的字符串生成类型安全的符号。

工作原理

1. 手动添加字符串到字符串目录，使用 + 按钮
2. 启用构建设置："Generate String Catalog Symbols"（在新项目中默认开启）
3. 使用符号而不是字符串

// ✅ 类型安全 - 编译器捕获拼写错误

Text(.appHomeScreenTitle)

符号生成规则

键名转换：

• App.HomeScreen.Title → .appHomeScreenTitle
• 移除句点，转换为驼峰命名法
• 在 LocalizedStringResource 上可用

代码示例

// SwiftUI 视图
struct ContentView: View {
    var body: some View {
        NavigationStack {
            Text(.introductionTitle)
                .navigationSubtitle(.subtitle(friendsPosts: 42))
        }
    }
}

// Foundation String
let message = String(localized: .curatedCollection)

// 使用 LocalizedStringResource 的自定义视图
struct CollectionDetailEditingView: View {
    let title: LocalizedStringResource

    init(title: LocalizedStringResource) {
        self.title = title
    }

    var body: some View {
        Text(title)
    }
}

CollectionDetailEditingView(title: .editingTitle)

自动注释生成

Xcode 26 使用设备端模型自动为可本地化字符串生成上下文注释。

启用功能

1. 打开 Xcode 设置 → 编辑
2. 启用 "automatically generate string catalog comments"
3. 添加到代码中的新字符串会自动接收生成的注释

示例

对于一个按钮字符串，Xcode 生成：

"The text label on a button to cancel the deletion of a collection"

此上下文帮助翻译人员理解字符串的使用位置和方式。

XLIFF 导出

自动生成的注释在导出的 XLIFF 文件中标记：

<trans-unit id="Grand Canyon" xml:space="preserve">
    <source>Grand Canyon</source>
    <target state="new">Grand Canyon</target>
    <note from="auto-generated">Suggestion for searching landmarks</note>
</trans-unit>

好处：

• 节省开发者编写翻译人员上下文的时间
• 提供一致、清晰的描述
• 提高翻译质量

Swift Package 和框架本地化

问题

SwiftUI 默认使用 .main 包。Swift Packages 和框架需要引用它们自己的包：

// ❌ 错误 - 使用主包，找不到字符串
Text("My Collections", comment: "Section title")

解决方案：#bundle 宏（Xcode 26 新增）

#bundle 宏自动引用当前目标的正确包：

// ✅ 正确 - 自动使用包/框架包
Text("My Collections", bundle: #bundle, comment: "Section title")

关键优势：

• 在主应用、框架和 Swift Packages 中工作
• 向后兼容较旧的操作系统版本
• 消除手动 .module 包管理

使用自定义表名

// 主应用
Text("My Collections",
     tableName: "Discover",
     comment: "Section title")

// 框架或 Swift Package
Text("My Collections",
     tableName: "Discover",
     bundle: #bundle,
     comment: "Section title")

自定义表符号访问

使用多个字符串目录进行组织时：

默认 "Localizable" 表

符号可直接在 LocalizedStringResource 上访问：

Text(.welcomeMessage)  // 来自 Localizable.xcstrings

注意：Xcode 自动从默认的 "Localizable" 表解析符号。很少需要显式选择表——仅用于调试或测试特定目录。

自定义表

符号嵌套在表命名空间中：

// 来自 Discover.xcstrings
Text(Discover.featuredCollection)

// 来自 Settings.xcstrings
Text(Settings.privacyPolicy)

大型应用的组织策略：

• Localizable.xcstrings - 核心应用字符串
• FeatureName.xcstrings - 功能特定字符串（例如，Onboarding、Settings、Discover）
• 好处：更易于管理、更清晰的所有权、更好的 XLIFF 组织

两种本地化工作流程

Xcode 26 支持两种互补的工作流程：

工作流程 1：字符串提取（推荐用于新项目）

流程：

1. 直接在代码中编写字符串
2. 使用 SwiftUI 视图（Text、Button）和 String(localized:)
3. Xcode 自动提取到字符串目录
4. 利用自动注释生成

优点：初始设置简单，立即开始

缺点：对字符串组织的控制较少

// ✅ 字符串提取工作流程
Text("Welcome to WWDC!", comment: "Main welcome message")

工作流程 2：生成的符号（推荐用于复杂度增长时）

流程：

1. 手动添加字符串到字符串目录
2. 通过类型安全符号引用
3. 组织到自定义表中

优点：更好的控制、类型安全、跨框架更易于维护

缺点：需要提前规划字符串目录结构

// ✅ 生成的符号工作流程
Text(.welcomeMessage)

在工作流程之间重构

Xcode 26 允许在不手动重写的情况下在工作流程之间转换。

将字符串转换为符号

1. 右键单击代码中的字符串字面量
2. 选择 "Refactor > Convert Strings to Symbols"
3. 预览所有受影响的位置
4. 自定义符号名称，然后确认
5. 应用到整个表或单个字符串

示例：

// 之前
Text("Welcome to WWDC!", comment: "Main welcome message")

// 重构后
Text(.welcomeToWWDC)

好处：

• 批量转换整个字符串目录
• 应用前预览更改
• 无需代码重写即可维护本地化

实施清单

采用 Xcode 26 生成的符号后，验证：

构建配置：

• "Generate String Catalog Symbols" 构建设置已启用
• 项目构建时没有 "Cannot find 'symbolName' in scope" 错误
• 清理构建成功 (Cmd+Shift+K，然后 Cmd+B)

字符串目录设置：

• 使用 + 按钮手动添加字符串到目录（非自动提取）
• 符号名称遵循约定（驼峰命名法，无句点）
• 自定义表按功能组织（如果使用多个目录）

Swift Package 集成：

• 包中的所有 Text() 和 String(localized:) 调用都使用 bundle: #bundle
• 在使用 #bundle 的地方添加了导入 Foundation
• 测试了包作为独立依赖项和作为依赖项的构建

重构和迁移：

• 在示例字符串上测试了重构工具
• 预览在应用前显示了预期的更改
• 旧字符串调用在过渡期间仍然有效

可选功能：

• Xcode 设置 → 编辑中启用了自动注释生成（可选）
• 测试了 AI 生成注释的准确性
• XLIFF 导出包含自动生成的注释

测试：

• 符号在 SwiftUI 预览中正确解析
• 本地化在所有支持的语言中工作
• 应用在最低支持的 iOS 版本上运行

资源

WWDC：2025-225、2023-10155、2022-10110

文档：/xcode/localization、/xcode/localizing-and-varying-text-with-a-string-catalog

技能：axiom-app-intents-ref、axiom-hig、axiom-accessibility-diag

每周安装次数

100

仓库

charleswiltgen/axiom

GitHub 星标数

606

首次出现

2026 年 1 月 21 日

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

opencode83

claude-code78

codex78

gemini-cli76

cursor74

github-copilot72