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.
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 codes | Chinese name | English 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:
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():
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():
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:
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.
