Scripting API

Players can switch languages from buttons inside the game. This page extends the quick start Demo with two buttons and one short script.

Before you start

Complete the quick start first: enable L10N, add English (en) and Simplified Chinese (zh-Hans), save Restart's Chinese translation “重新开始”, and associate the button Label with the correct Key.

The PinK editor's display language is independent of the game's language choices.

1. Add a language script

Create 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({}) reads the language resources already prepared by the project. Each button handler waits for initialization before calling changeLanguage(). Attach this script once in the scene.

2. Add and bind two buttons

1. Open assets/main.scene. Create an empty LanguageController node under Canvas and attach LanguageButtons.ts to it.
2. Add two Buttons under Canvas, named EnglishButton and ChineseButton. Set their visible text to English and “简体中文” and place them clear of the existing game UI.
3. In EnglishButton's Button component, add a Click Events item. Drag LanguageController to its target, then choose LanguageButtons → useEnglish.
4. Bind ChineseButton to LanguageButtons → useSimplifiedChinese in the same way, then save the scene.

Use fixed language names on these buttons so players can find them in either game language.

Choose LanguageController as the target, then the component and handler

3. Click to switch in preview

Run the scene. Select English, then “简体中文”, and watch the original Restart button: it should display Restart and “重新开始” respectively. Associated L10nLabel components update with the language.

If nothing changes, first check the Click Events targets and methods, then the saved translation, node Key and scene.

In a built game, the current Runtime saves the selected language and restarts the game. Save any player progress that needs to survive this restart. Before delivery, include en and zh-Hans in Build languages. Switching in editor preview does not change the build default.

Click a language button and check the original Restart label

Other scripting uses

Use	Example
Current language	l10n.currentLanguage
Available languages	l10n.languages
Read a translation	l10n.t('game.score')
Insert dynamic text	l10n.t('game.score', { score: String(score) })
Choose a quantity form	l10n.t('inventory.item', { count: 2 })

For example, game.score can have the English source Score: and Chinese translation “得分：”. Prepare and save the Key and translations first. Keep variable names, Keys and placeholders such as unchanged.

The collector recognizes static first arguments such as l10n.t('game.score'). If collection creates a Key with empty source text, fill and save it through Complete source text. Prepare entries separately for variable or concatenated Keys.

l10n.t() returns the result of one lookup. For a score or another Label updated by scripts, read the translation again when the value or language changes. Wait for initialization before reading translations. L10nLabel already listens for language changes; regular Labels can listen to L10nListenEvent.languageChanged and remove the listener when their component is destroyed.