Skip to content

Multilingual Best Practices ​

This guide is for minigame CPs. For App-side language configuration, see App Multilingual Best Practices.

1. Read the Language and Select Text and Resources ​

By default, read the current App language from sud.getAppBaseInfo().language and map it to a language supported by the game. The following example supports Simplified Chinese, Traditional Chinese, and English, falling back to English when no match is found.

javascript
const messages = {
    'zh-Hans': { play: '开始游戏' },
    'zh-Hant': { play: '開始遊戲' },
    en: { play: 'Play' }
};

const info = sud.getAppBaseInfo();
const tag = typeof info.language === 'string'
    ? info.language.trim().replace(/_/g, '-').toLowerCase()
    : '';

let resourceLanguage = 'en';
if (/^zh-hant(?:-|$)/.test(tag)) {
    resourceLanguage = 'zh-Hant';
} else if (/^zh-hans(?:-|$)/.test(tag)) {
    resourceLanguage = 'zh-Hans';
} else if (/^zh-(tw|hk|mo)(?:-|$)/.test(tag)) {
    resourceLanguage = 'zh-Hant';
} else if (/^zh-(cn|sg)(?:-|$)/.test(tag)) {
    resourceLanguage = 'zh-Hans';
}

const text = messages[resourceLanguage];
// Set the button label to text.play.

Use the same resource language for text, images, and audio. Fall back to the game's defaults for missing translations or resources.

Language Code Reference ​

Language codesChinese nameEnglish name
en,en-US通用English (US)
zh,zh-CN,zh-Hans简体中文Simplified Chinese
zh,zh-TW,zh-HK,zh-Hant繁体中文Traditional Chinese
ru,ru-RU俄语Russian
ar阿拉伯语Arabic
de,de-DE德语German
en,en-GB英语(英国)English (UK)
ca加泰罗尼亚语Catalan
hr,hr-HR克罗地亚语Croatian
en,en-CA英语(加拿大)English (Canada)
ur乌尔都语Urdu
uk,uk-UA乌克兰语Ukrainian
it,it-IT意大利语Italian
hu,hu-HU匈牙利语Hungarian
fr,fr-FR法语French
hi,hi-IN印地语Hindi
id,id-ID印尼语Indonesian
sv,sv-SE瑞典语Swedish
gu,gu-IN古吉拉特语Gujarati
nl,nl-NL荷兰语Dutch
pt,pt-PT葡萄牙语(葡萄牙)Portuguese (Portugal)
tr,tr-TR土耳其语Turkish
da,da-DK丹麦语Danish
es,es-ES西班牙语(西班牙)Spanish (Spain)
kn,kn-IN坎纳达语Kannada
es,es-MX西班牙语(墨西哥)Spanish (Mexico)
or,or-IN奥里亚语Odia
pt,pt-BR葡萄牙语(巴西)Portuguese (Brazil)
bn,bn-IN孟加拉语Bengali
he,he-IL希伯来语Hebrew
en,en-AU英语(澳大利亚)English (Australia)
el,el-GR希腊语Greek
ja,ja-JP日语Japanese
ko,ko-KR韩语Korean
nb,nb-NO挪威语Norwegian
cs,cs-CZ捷克语Czech
sk,sk-SK斯洛伐克语Slovak
sl,sl-SI斯洛文尼亚语Slovenian
pa,pa-IN旁遮普语Punjabi
fr-CA法语(加拿大)French (Canada)
pl,pl-PL波兰语Polish
te,te-IN泰卢固语Telugu
ta,ta-IN泰米尔语Tamil
th,th-TH泰语Thai
ro,ro-RO罗马尼亚语Romanian
fi,fi-FI芬兰语Finnish
vi,vi-VN越南语Vietnamese
mr,mr-IN马拉地语Marathi
ml,ml-IN马拉雅拉姆语Malayalam
ms,ms-MY马来语Malay

2. Change Language with Cocos i18n ​

Map the App language to the plugin language ID configured in your project, such as zh-CN to zh. Initialize the language after the scene has loaded, and refresh the current scene when switching languages:

typescript
import * as i18n from 'db://i18n/LanguageData';

i18n.init('en');
i18n.updateSceneRenderers();

Update any text and resources rendered by your own game code as well. No restart is required.

3. Change Language with Cocos l10n ​

In SUD Runtime, the plugin's default restart does not restart the minigame. Save the necessary game state, switch to a configured language, and explicitly call sud.restart():

typescript
import { l10n } from 'db://localization-editor/l10n';

l10n.changeLanguage('en-US');
sud.restart();

After the restart, l10n reads the saved language. Call sud.restart() only once per language change.

4. Implement Custom Language Switching ​

If the game manages its own language and requires a restart to apply a change, save the language and necessary game state before calling sud.restart():

javascript
localStorage.setItem('game.language', 'en-US');
sud.restart();

At startup, prefer the user's in-game language selection. If no selection exists, follow the App language, then map it to a language supported by the game:

javascript
const language = localStorage.getItem('game.language')
    || sud.getAppBaseInfo().language
    || 'en-US';

To restore “Follow App,” clear game.language and reinitialize the game. Projects using l10n should use the plugin's language storage without maintaining this extra key.

Complete all save operations before calling sud.restart(). An in-game language selection does not change the App UI or the SDK loading screen language.