Cocos

简体中文

English

简体中文

English

主题

Localization Editor Api ​

快速开始 ​

核心功能 l10n ​

l10n 提供了核心翻译功能以及 ICU 功能，同时也提供的切换语言的功能。

我们会将切换后的目标语言存储于 localStorage 中，同时也会自动重启项目运行时，并在下次启动时读取 localStorage 配置以完成整个语言切换流程。

注意：因此我们希望用户在切换语言之前务必处理好数据持久化工作。

导入 l10n 模块 ​

localization-editor 所提供的所有 API 都将从 db://localization-editor/l10n 进行具名导入，导入示例如下：

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

使用翻译api ​

typescript
// 任意 component 组件代码中

// l10n 是 localization 的核心功能
import { l10n } from 'db://localization-editor/l10n'
import { _decorator, Label, Component } from 'cc';

@ccclass('SomeComponent')
class SomeComponent extends Component {
    // ......
    someMethod() {
        // 将返回 this_is_an_apple 所对应文案
        const text = l10n.t("this_is_an_apple")
    }
    // ......
}

API详细说明 ​

L10nManager ​

导入示例：

ts
import { L10nManager } from 'db://localization-editor/l10n'

描述：

通常我们不建议您自行使用或构造该类型。

而我们提供了l10n作为全局单例以使用翻译功能。

索引 ​

构造函数 ​

  • L10nManager private

全局变量 ​

l10n ​

定义: const l10n: L10nManager

静态属性 ​

LOCAL_STORAGE_LANGUAGE_KEY ​

定义: static LOCAL_STORAGE_LANGUAGE_KEY: string

描述: 当调用changeLanguage切换游戏语言时，将使用localStorage 存储所切换的目标语言标记，并且使用LOCAL_STORAGE_LANGUAGE_KEY作为localStorage的key

备注：

默认值localization-editor/language

实例方法 ​

config ​

定义: config(options: L10nOptions): void

描述: 用于配置l10n的某些设置，探索更多选项可以查看L10nOptions

用例:

ts
l10n.config({
    // 用于在默认语言没有找到相应翻译时，以该值进行补充显示
    fallbackLanguage: 'zh-Hans-CN',
    // 如果不喜欢LOCAL_STORAGE_LANGUAGE_KEY的默认值，可以在此修改，但是需要确保在changeLanguage之前
    localStorageLanguageKey: 'localization-editor/langauge'
})
changeLanguage ​

定义: changeLanguage(language: Intl.BCP47LanguageTag): void

描述: 用于动态切换语言，请查看BCP47 Language Tag以获得更多信息

用例:

ts
l10n.changeLanguage('zh-Hans-CN')

注意: 在调用此方法后，会自动重启游戏，请务必做好数据持久化工作。

t ​

定义: t(key: L10nKey, options?: StandardOption): L10nValue

描述: 根据传入的L10nKey，返回当前语言数据中所对应的L10nValue，探索更多选项可以查看StandardOption

用例:

ts
console.log(l10n.t('this_is_apple'))
// 这是一个苹果

注意: 语言数据需要配合 Localization Editor 扩展在编译后生成。

exists ​

定义: exists(key: L10nKey): boolean

描述: 返回是否存在key

用例:

ts
console.log(l10n.exists('test_key'))
currentLanguage ​

定义: get currentLanguage(): Intl.BCP47LanguageTag

描述: 返回当前语言的BCP47 Language Tag

用例:

console.log(l10n.currentLanguage)
// 'zh-Hans-CN'
languages ​

定义: get languages(): readonly Intl.BCP47LanguageTag[]

描述: 返回当前可用语言的BCP47 Language Tag数组，可利用该方法作为切换语言下拉框的数据源

用例:

ts
console.log(l10n.languages)
// ['zh-Hans-CN', 'en-US']
direction ​

定义: direction(language?: Intl.BCP47LanguageTag): TextInfoDirection

描述: 绝大多数语言都尊崇从左到右的阅读习惯，但某些语言却例外比如阿拉伯语，此方法可以得知所传入语言的TextInfoDirection

用例:

ts
console.log(l10n.direction('ar'))
// 'rtl'
on ​

定义: on(event: L10nListenEvent, callback: (...args: any[]) => void)

描述: 用于注册l10n的L10nListenEvent事件回调，比如languageChanged

用例:

ts
l10n.on(L10nListenEvent.languageChanged, (...args: any[]) => {
    //在切换语言后的一些操作，某些数据可以放在这里持久化，之后便会重启整个游戏场景
})
off ​

定义: off(event: L10nListenEvent, callback: (...args: any[]) => void)

描述: 用于反注册l10n的L10nListenEvent事件回调

请务必使on与off成对出现，确保正确的销毁无用数据

别名 ​

别名原类型
L10nKeystring
L10nValuestring
TextInfoDirection'ltr' / 'rtl'
FallbackLanguagestring / readonly string[] / FallbackLanguageObjectList / ((language: Intl.BCP47LanguageTag) => string / readonly string[] / FallbackLanguageObjectList

接口 ​

L10nOptions ​

函数/变量名类型可选
fallbackLanguagefalse / FallbackLanguage是
localStorageLanguageKeystring是
beforeTranslate(key: L10nKey) => L10nValue是
afterTranslate(key: L10nKey) => L10nValue是
returnNullboolean是
returnEmptyStringboolean是

ResourceList ​

函数/变量名类型可选
defaultLanguageIntl.BCP47LanguageTag是
fallbackLanguageIntl.BCP47LanguageTag是
languagesIntl.BCP47LanguageTag[]否

ResourceBundle ​

函数/变量名类型可选
[language: Intl.BCP47LanguageTag]ResourceData否

ResourceData ​

函数/变量名类型可选
[namespace: string]ResourceItem否

ResourceItem ​

函数/变量名类型可选
[key: string]any否

FallbackLanguageObjectList ​

函数/变量名类型可选
[language: string]readonly string[]否

StandardOption ​

函数/变量名类型可选
countnumber是
defaultValueL10nValue是
languageIntl.BCP47LanguageTag是
fallbackLanguageFallbackLanguage是

枚举 ​

L10nListenEvent ​

函数/变量名类型
languageChangedlanguageChanged
onMissingKeymissingKey