多语言最佳实践
本文面向小游戏 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 加载页的语言。
