脚本 API

除了在本地化编辑器中选择预览语言，也可以让玩家在游戏里点击按钮切换语言。本页沿用快速开始的游戏 Demo，只添加两个按钮和一份短脚本。

开始前

先完成快速开始：项目已启用 L10N，英语（en）和简体中文（zh-Hans）均已添加，Restart 的中文译文“重新开始”已保存，按钮 Label 已关联正确的 Key。

编辑器界面使用哪种语言，不影响游戏中的这两个语言选项。

1. 添加语言切换脚本

在 assets/scripts 下新建 LanguageButtons.ts，填写：

import { _decorator, Component } from 'cc';
import { l10n } from 'db://localization-editor/l10n';

const { ccclass } = _decorator;

@ccclass('LanguageButtons')
export class LanguageButtons extends Component {
  private ready!: Promise<void>;

  protected onLoad(): void {
    this.ready = l10n.createIntl({});
  }

  public async useEnglish(): Promise<void> {
    await this.ready;
    await l10n.changeLanguage('en');
  }

  public async useSimplifiedChinese(): Promise<void> {
    await this.ready;
    await l10n.changeLanguage('zh-Hans');
  }
}

createIntl({}) 读取项目已经准备好的语言资源；点击按钮时，先等待初始化，再调用 changeLanguage()。这份脚本只需要在场景中挂载一次。

2. 添加按钮并绑定方法

1. 打开 assets/main.scene，在 Canvas 下新建空节点 LanguageController，将 LanguageButtons.ts 挂到这个节点。
2. 在 Canvas 下添加两个 Button，分别命名为 EnglishButton、ChineseButton，把可见文字设为 English 和“简体中文”，放在不遮挡原有界面的位置。
3. 在 EnglishButton 的 Button 组件中，为 Click Events 添加一项。将 LanguageController 拖到事件目标，选择 LanguageButtons → useEnglish。
4. 给 ChineseButton 同样绑定 LanguageButtons → useSimplifiedChinese，然后保存场景。

两个按钮直接使用固定语言名称，方便玩家在任何语言下找到入口。

目标选择 LanguageController，再选择组件与方法

3. 在游戏预览中点击切换

运行场景，先点击 English，再点击“简体中文”。观察原有的 Restart 按钮：英语时显示 Restart，简体中文时显示“重新开始”。已绑定的 L10nLabel 会随语言变化更新。

如果点击后没有变化，先检查两个 Click Events 是否指向正确节点和方法，再确认译文、节点 Key 和场景都已保存。

在构建后的游戏中，当前 Runtime 会保存所选语言并重启游戏；实际游戏应先保存需要保留的玩家进度。发布前按构建语言配置包含 en 和 zh-Hans。编辑器预览中的切换不代表构建默认语言已改变。

点击语言按钮，观察 Restart 文案随之变化

还可以用脚本做什么

用法	简单示例
读取当前语言	l10n.currentLanguage
获取可用语言	l10n.languages
读取一条译文	l10n.t('game.score')
传入动态文字	l10n.t('game.score', { score: String(score) })
使用数量变体	l10n.t('inventory.item', { count: 2 })

例如 game.score 的英语原文可写成 Score: ，中文译文写成“得分：”。Key 和译文要先准备并保存；脚本中的变量名、Key 和 占位符都不翻译。

收集器能识别 l10n.t('game.score') 这样的静态字符串首参数。收集后若源文为空，在“补充源文案”页面填写并保存。变量或拼接得到的 Key 需要另行准备条目。

l10n.t() 返回当次查询结果。对于分数等由脚本赋值的动态文字，需要在数值或语言变化时重新读取；初始化尚未完成时不要提前取译文。L10nLabel 已自动监听语言变化，普通 Label 可使用 L10nListenEvent.languageChanged 自行刷新，并在组件销毁时解除监听。