README.zh-CN.md

Localization Editor API

快速开始

核心功能 l10n

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

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

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

导入l10n模块

localization-editor所提供的所有api都将从db://localization-editor/l10n进行具名导入

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

使用翻译api

// 任意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

---

• 接口:ResourceList

• 接口:ResourceBundle

• 接口:ResourceData

• 接口:ResourceItem

• 接口:FallbackLanguageObjectList

• 接口:L10nOptions

• 接口:StandardOption

---

• 枚举:L10nListenEvent

---

• 别名:L10nKey

• 别名:L10nValue

• 别名:TextInfoDirection

• 别名:FallbackLanguage

---

L10nManager

导入示例：

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

用例:

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

---

changeLanguage

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

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

用例:

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

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

---

t

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

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

用例:

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

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

无法在静态初始化中使用l10n.t， 比如static name = l10n.t('xxx_name')

变量作为参数时无法扫描，比如let name = 'this_is_apple'; l10n.t(name)

---

exists

定义: exists(key: L10nKey): boolean

描述: 返回是否存在key

用例:

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数组，可利用该方法作为切换语言下拉框的数据源

用例:

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

---

direction

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

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

用例:

console.log(l10n.direction('ar'))
// 'rtl'

---

on

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

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

用例:

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

---

off

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

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

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

---

别名

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

---

接口

L10nOptions

函数/变量名	类型	可选
fallbackLanguage	false / FallbackLanguage	是
localStorageLanguageKey	string	是
beforeTranslate	(key: L10nKey) => L10nValue	是
afterTranslate	(key: L10nKey) => L10nValue	是
returnNull	boolean	是
returnEmptyString	boolean	是

---

ResourceList

函数/变量名	类型	可选
defaultLanguage	Intl.BCP47LanguageTag	是
fallbackLanguage	Intl.BCP47LanguageTag	是
languages	Intl.BCP47LanguageTag[]	否

ResourceBundle

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

---

ResourceData

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

---

ResourceItem

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

---

FallbackLanguageObjectList

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

---

StandardOption

函数/变量名	类型	可选
count	number	是
defaultValue	L10nValue	是
language	Intl.BCP47LanguageTag	是
fallbackLanguage	FallbackLanguage	是

---

枚举

L10nListenEvent

函数/变量名	类型
languageChanged	languageChanged
onMissingKey	missingKey