Skip to content

多语言最佳实践 ​

本文面向小游戏 CP。App 侧的语言配置见App 多语言最佳实践。

1. 获取语言并选择文案、资源 ​

默认通过 sud.getAppBaseInfo().language 获取 App 当前语言,将其映射为游戏支持的语言。以下支持简体中文、繁体中文和英文,未匹配时使用英文。

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];
// 将 text.play 设置为按钮文案。

文案、图片、音频使用同一个资源语言;缺失的翻译或资源使用游戏默认值。

语言代码对照表 ​

语言代码中文名称英文名称
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. Cocos i18n 切换语言 ​

将 App 语言映射为项目配置的插件语言 ID,例如 zh-CN 对应 zh。场景加载完成后初始化语言,切换时刷新当前场景:

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

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

游戏自行渲染的文本和资源同步更新,无需重启。

3. Cocos l10n 切换语言 ​

在 SUD Runtime 中,插件默认重启不能完成小游戏重启。先保存必要业务状态,再切换到已配置的语言,并显式调用 sud.restart():

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

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

重启后由 l10n 读取已保存的语言,每次切换只调用一次 sud.restart()。

4. 自定义语言切换 ​

游戏自行管理语言、且需要重启才能完成切换时,先保存语言和必要业务状态,再调用 sud.restart():

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

游戏入口优先读取用户在游戏内的选择;未选择时跟随 App,再按游戏支持范围进行映射:

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

恢复“跟随 App”时清除 game.language,再重新初始化。使用 l10n 的项目沿用插件的语言存储,不需要另外维护该键。

sud.restart() 前完成所有保存操作;小游戏内的语言选择不会改变 App UI 或 SDK 加载页的语言。