本地化 iOS 应用
翻译 Apple 字符串目录或旧版资源,保留共享文件中的语言区域,再到 Xcode 和应用中验证结果。
iOS 应用可以在资源文件中添加一种语言,而无需更改现有的本地化查找调用。Lingo.dev 负责翻译这些资源;用户最终看到的资源包、字符串表、语言区域和变体,仍由 Xcode 和应用决定。
沿用项目当前加载的格式。字符串目录将多种语言保存在同一个 .xcstrings 文件中,而 .strings 和 .stringsdict 资源则为每个语言区域使用独立文件。这一区别决定了结果的写入位置,以及更新时需要保护哪些内容。
确定以哪些资源为准 #
对于使用字符串目录的项目,请先确认开发语言、支持的目标语言,以及应用加载的目录。Xcode 15 引入了 .xcstrings,通常命名为 Localizable.xcstrings。项目可以通过多个目录,按功能或资源包组织消息;请纳入为待本地化界面提供内容的所有目录。
对于旧版资源,请确认相关的 .lproj 目录、字符串表和复数字典。Base.lproj 可以包含基础界面资源,但仅凭该目录的存在,并不能让翻译工具确定应使用哪种源语言或哪个字符串表。请确保项目的开发语言设置与文件配置一致。
翻译前,先让界面文本通过本地化查找调用获取。翻译文件不会替换硬编码的界面字符串,也不会将资源注册到 Xcode 目标中。请保留说明说话者和所在界面的注释,供审核者参考。现有的字符串目录处理器会保留这些注释,但不会将其纳入翻译单元的提示,因此请将生成翻译所必需的上下文写入本地化引擎支持的指导信息中。
配置共享字符串目录 #
在项目根目录安装当前版本的 CLI 并完成关联:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'App/Localizable.xcstrings' --yes
lingo link对于该路径下的目录,生成的 .lingo/config.json 应采用以下结构:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es", "fr"],
"files": [{ "pattern": "App/Localizable.xcstrings" }]
}请保留关联时生成的标识符,不要照搬占位符。文件扩展名决定使用 xcode-xcstrings。每个目标语言的结果都会写入同一个目录路径,在添加语言区域条目的同时,保留源语言和其他语言区域。此共享文件格式不支持单独的 targetPath。
源文本值保存在共享结构中:
{
"sourceLanguage": "en",
"strings": {
"Welcome": {
"comment": "Greeting on the signed-in home screen",
"localizations": {
"en": { "stringUnit": { "state": "translated", "value": "Welcome" } }
}
}
},
"version": "1.0"
}翻译后,请在 en 旁查找所请求的语言区域条目。处理器也支持源语言的复数和设备变体叶节点,并会跳过标记为 shouldTranslate: false 的条目。如果条目没有源语言的本地化内容,其键就会被用作源文本;技术性键名不能替代实际要表达的消息。Apple 字符串目录介绍了这些选择规则,以及当前源内容为何必须与现有目录保持一致。
让旧版文件使用各自的路径 #
对于旧版项目,请使用以下文件条目,替代共享目录条目:
[{ "pattern": "App/en.lproj/Localizable.strings" }, { "pattern": "App/en.lproj/Localizable.stringsdict" }]仅纳入项目实际使用的资源。文件扩展名决定使用哪个处理器;西班牙语输出应写入 App/es.lproj/。请确保项目的开发语言设置与此处选择的源语言一致。
字符串键和格式占位符是运行时约定的一部分。请保留 %@、位置参数,以及调用方预期的类型。.stringsdict 包含复数变量结构,该结构必须与其格式字符串保持一致。请参阅 Apple 字符串和字符串字典,了解各自的约定,不要将它们当作普通 XML 或文本随意处理。
翻译并检查合并后的结果 #
替换前,请通过版本控制或另存副本保留当前目录。为保护本地修改,提交时请勿使用 --wait,并在获取结果前检查 lingo pull --dry-run。如有差异,请先协调处理,不要强制覆盖。等待完成后的回写没有拉取操作所做的即时冲突检查;请参阅保留已审核的翻译。
进行首次翻译时,仅在等待期间目录保持不变的情况下使用以下命令。向现有项目添加语言区域前,请先完成现有语言区域的常规源内容更新,获取并检查结果,再在添加语言区域和回填翻译期间保持该源内容版本不变。添加语言介绍了必须遵循的操作顺序:
lingo push --backfill-missing --wait即使文件已经存在,共享目录仍会按语言区域分别规划处理。请检查所请求的语言区域条目,而不是寻找新的文件名。首次普通推送可以只建立源内容基线,不进行翻译。常规源内容变更后,请使用 lingo push --wait;如果不等待,请在提交时所用的 checkout 中通过 lingo pull 获取已记录的结果。
要修正文案,请在 Xcode 中编辑目标语言条目。CLI 的 --force 仍可能复用未变更目录中已有的翻译。修改指导信息后,若要重新生成单个条目,请使用目录修正流程,该流程会保留源内容和相邻条目的翻译。
lingo purge 会跳过字符串目录,因为源语言和目标语言共用同一路径。要重新生成选定的翻译,请使用字符串目录修正工作流。
在 Xcode 和代表性界面中验证 #
在 Xcode 中打开输出,确认目录或旧版文件已纳入预期的目标和资源包。使用项目现有的构建方案进行构建。以目标语言配置运行应用,并检查一个包含简单标签、格式化值以及复数或设备变体的界面。
将目标语言中的占位符与调用代码进行比对。测试能在各语言中触发不同复数形式的数量值;英语的复数类别无法完整涵盖所有目标语言的规则。确认合并后的目录仍保留未修改的语言区域。根据适用情况,审核长标签、无障碍文本、截断情况及从右到左的显示行为。
Xcode 的构建检查可以发现资源问题,文本含义则需由语言审核者或适用的测量项目检查。lingo check 无法证明 .xcstrings 的完整性,也无法证明 Apple 的复数处理行为正确。
确保自动化保留共享文件 #
将源内容、已接受的目标语言内容、配置和 .lingo/lock.json 保存在一起,再选择 GitHub App 或 CI 运行器来处理周期性工作。运行器自行管理身份验证、状态及可供审核的回写。审核字符串目录的差异时,应将其视为共享文件的变更:接受前,先确认源内容版本、发生变更的语言区域,以及保留下来的语言区域。
对于跨平台项目,请分别使用 Android 和 Flutter 工作流处理 XML 限定符和 ARB 生成。每个平台仍需单独检查资源加载和界面渲染。