概述与快速开始

L10N 是什么

L10N 是 PinK 中用于管理 Cocos 项目多语言内容的本地化插件。当游戏需要面向不同语言的玩家时，你可以用它集中维护文字译文和各语言的媒体资源，再检查它们在项目中的显示效果。

例如，同一个游戏的英语版本显示 Restart，中文版本显示“重新开始”；带文字的图片、配音或字体也可能需要使用不同资源。L10N 用于管理这些项目内容，切换 PinK 编辑器自身的界面语言则是另一项设置。

它能帮你完成什么

L10N 提供面板和 Chat 两个入口。面板适合逐项编辑与审阅；Chat 适合描述任务，由 Agent 按范围查询或修改项目。首次使用可完成本页的双语示例，再按需要查看功能说明。

你要完成的事	阅读位置
收集内容，管理语言、译文、变体、组件和媒体，导入导出文件或清理数据	管理本地化内容
使用自动翻译生成初译，通过 Chat 执行本地化任务	自动翻译与 Chat
在游戏脚本中读取文字、使用复数、切换语言和监听变化	脚本 API
检查显示效果，配置构建语言并验证发布结果	预览与构建

翻译服务是可选的。本页教程通过手工输入完成第一条译文，无需先配置 AI 或第三方服务。

内容如何对应到不同语言

每个本地化条目通过 Key 标识。同一条目可以保存中文、英语等不同语言的文字，或对应不同的媒体资源。组件和运行时根据条目及所选语言使用对应内容。

以界面文字为例：Label 节点通过 L10nLabel 的 Key 关联翻译条目，条目保存各语言译文，预览时选择要显示的语言。 因此，修改译文通常不需要重新指定节点的 Key；保存译文、关联节点和选择语言则分别承担不同的作用。

先完成一条中英文文字

这一页使用手册配套的游戏 Demo，把已有的 Restart 按钮文字变成可以切换的中英文内容。完成后，同一个按钮在英语预览中显示 Restart，在中文预览中显示“重新开始”。

整个过程只做一条文字：收集原文、保存译文、确认节点关联、切换预览。暂时不需要翻译服务账号，也不需要准备翻译文件或构建安装包。

英语预览：按钮显示 Restart

简体中文预览：同一个按钮显示“重新开始”；Pink Demo 名称保持原样

开始前：打开游戏 Demo

先按打开已有 Cocos 项目：使用 Pink Demo 跟随教程准备项目。本页直接使用 Demo 中已有的场景和按钮，不需要新建节点或修改原文。

1. 在 PinK 中打开 pink-game-demo 项目根目录。
2. 打开 assets/main.scene，在层级管理器中找到 Canvas/ResetButton/Label。
3. 预览场景，确认按钮显示 Restart，并能正常重置分数。

后面会收集 assets 目录中的场景文字，可能为场景添加本地化组件并保存场景。建议在 Demo 的可恢复副本中练习。

确认能看见 Restart 后再继续。 如果此时按钮文字不可见，应先检查场景预览；启用本地化不会修复原场景的显示问题。

1. 告诉编辑器：原文使用英语

从项目菜单选择“打开本地化编辑器”。首次打开时，面板提示项目尚未启用本地化，点击“启用（Enable）”。

等待准备完成，在“源语言（原文语言）”中选择英语。游戏 Demo 的 Restart 是英语原文；源语言指原始内容使用的语言，与 PinK 自身界面使用什么语言无关。

面板中还会出现翻译服务、收集和语言列表等区域。这次先不用填写翻译服务：下一步直接收集场景中的英语原文。

本页使用“源语言（原文语言）”“收集并统计”和“编译语言”三个区域

2. 把 Restart 收进翻译表

翻译表还不知道场景中的这条文字。现在通过收集，把它加入可以翻译的条目。

1. 在“从资源文件收集”区域打开“配置收集组”。
2. 使用“收录目录”旁的目录选择器，选择游戏 Demo 的 assets 目录。先使用一个收集组，不添加额外过滤规则。
3. 点击“收集并统计（Collect and count）”，等待完成。
4. 在“编译语言”列表中找到英语行，点击“补充源文案（Complete source text）”。
5. 在打开的页面切换到“已填写”，找到 Restart 条目。场景中还有其他英语文字，本页只使用这一条。

找到 Restart 后选中这一行，展开页面下方的“条目详情（Entry details）”，记下或复制 Key。它是连接场景节点和译文的标识，不需要翻译。

在“已填写”中选择 Restart，记录下方显示的 Key

如果找不到条目，先确认 assets/main.scene 已保存，收录目录是游戏 Demo 的 assets。如果是已经配置过本地化的项目，也可以用节点 L10nLabel 中的 Key 对照条目。不要在原文还没找到时继续添加其他语言。

3. 给同一条目填写中文

返回首页的语言列表，再进行下面的操作：

1. 点击“添加新语言”，搜索并选择简体中文，然后点击“添加”。
2. 在简体中文行点击“翻译（Translate）”。
3. 在“未翻译”中按上一步记录的 Key 找到条目，确认该行原文是 Restart。
4. 在译文位置输入“重新开始”。
5. 点击翻译页的“保存（Save）”。

输入文字只修改草稿，点击保存才把译文写入项目。 保存后返回语言列表，再次进入简体中文翻译页，确认同一条目仍显示“重新开始”。

输入“重新开始”后，页面显示未保存更改；点击右上角“保存”

语言行的“翻译”用于打开编辑页面；翻译页中的自动翻译按钮用于请求初译。本例直接手工填写并保存。

4. 确认场景节点使用的就是这条译文

回到 assets/main.scene，选择 Canvas/ResetButton/Label，在属性检查器中找到收集添加的 L10nLabel。

对照它的 Key 与刚才翻译条目的 Key：

• **两者一致：**保留这个值，保存场景后进入下一步。
• **两者不同：**打开 Key 选择器，搜索刚才的条目并选中，点击 Key 编辑器的“保存”，再保存场景。

Key 旁提供选择、生成和编辑图标；修改 Key 后会显示“保存”和“重置”。没有修改时不需要寻找保存按钮。

这里保存的是节点关联，不是中文译文。以后只修改译文时，可以保留这个 Key，让节点继续使用同一条目的新内容。

Key 选择器中的 Restart 已勾选，其 Key 与英语源文案页一致

5. 在同一场景对照中英文

回到本地化编辑器的语言列表，在简体中文行点击“预览（Preview）”，检查项目预览中的 Restart 按钮。再选择英语行的“预览”，检查同一个按钮。

选择的预览语言	应看到的文字
英语	Restart
简体中文	重新开始

能得到这组结果，就完成了第一条文字的本地化。你已经连接了三件事：翻译表里的译文、节点上的 Key、正在预览的语言。

若没有得到对照结果，按顺序停下来检查：

1. 简体中文翻译页重新打开后是否仍有“重新开始”；没有就先保存译文。
2. 节点 Key 是否与该条目一致；不同就更正关联并保存场景。
3. 是否点击了简体中文行的预览，并查看游戏 Demo 中的 assets/main.scene。

如果“预览”按钮不可用，查看面板和按钮给出的项目连接提示；不要通过删除翻译数据尝试修复连接问题。

下一步

完成双语示例后，可以在管理本地化内容中扩大收集范围、填写复数和关联媒体，或通过导入导出与翻译人员协作。

需要批量初译或让 Agent 处理任务时，阅读自动翻译与 Chat；想在游戏中点击按钮切换语言，继续脚本 API。交付前按预览与构建检查语言、资源和布局。