cuongnm
/
super-hero
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
super-hero/extensions/localization-editor/README.md

352 lines
9.2 KiB
Markdown
Raw Normal View History

'init'
2024-04-19 03:49:41 -07:00
# Localization Editor Api
## 快速开始
### [核心功能 `l10n`](#l10n)
l10n提供了核心翻译功能以及icu功能，同时也提供的切换语言的功能。
我们会将切换后的目标语言存储于`localStorage`中，同时也会自动重启项目运行时，并在下次启动时读取`localStorage`配置以完成整个语言切换流程。
> ***因此我们希望用户在切换语言之前务必处理好数据持久化工作***
### 导入[`l10n`](#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`](#l10nmanager)
---
- 接口:[`ResourceList`](#resourcelist)
- 接口:[`ResourceBundle`](#resourcebundle)
- 接口:[`ResourceData`](#resourcedata)
- 接口:[`ResourceItem`](#resourceitem)
- 接口:[`FallbackLanguageObjectList`](#fallbacklanguageobjectlist)
- 接口:[`L10nOptions`](#l10noptions)
- 接口:[`StandardOption`](#standardoption)
---
- 枚举:[`L10nListenEvent`](#l10nlistenevent)
---
- 别名:[`L10nKey`](#别名)
- 别名:[`L10nValue`](#别名)
- 别名:[`TextInfoDirection`](#别名)
- 别名:[`FallbackLanguage`](#别名)
---
# `L10nManager`
导入示例：
```ts
import { L10nManager } from 'db://localization-editor/l10n'
```
描述：
通常我们不建议您自行使用或构造该类型。
而我们提供了[`l10n`](#l10n)作为全局单例以使用翻译功能。
---
## 索引
### 构造函数
- `L10nManager` **private**
---
### 全局变量
#### `l10n`
定义: `const l10n: L10nManager`
---
### 静态属性
#### `LOCAL_STORAGE_LANGUAGE_KEY`
定义: `static LOCAL_STORAGE_LANGUAGE_KEY: string`
描述: 当调用[`changeLanguage`](#changelanguage)切换游戏语言时，将使用`localStorage`
存储所切换的目标语言标记，并且使用[`LOCAL_STORAGE_LANGUAGE_KEY`](#localstoragelanguagekey)作为`localStorage`的key
备注：
| 默认值 | localization-editor/language |
|-----|------------------------------|
---
### 实例方法
#### `config`
定义: `config(options: L10nOptions): void`
描述: 用于配置l10n的某些设置，探索更多选项可以查看[`L10nOptions`](#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`](https://www.techonthenet.com/js/language_tags.php)以获得更多信息
用例:
```ts
l10n.changeLanguage('zh-Hans-CN')
```
> ***注意: 在调用此方法后，会自动重启游戏，请务必做好数据持久化工作***
---
#### `t`
定义: `t(key: L10nKey, options?: StandardOption): L10nValue`
描述: 根据传入的L10nKey，返回当前语言数据中所对应的L10nValue，探索更多选项可以查看[`StandardOption`](#standardoption)
用例:
```ts
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
用例:
```ts
console.log(l10n.exists('test_key'))
```
---
#### `currentLanguage`
定义: `get currentLanguage(): Intl.BCP47LanguageTag`
描述: 返回当前语言的[`BCP47 Language Tag`](https://www.techonthenet.com/js/language_tags.php)
用例:
```ts
console.log(l10n.currentLanguage)
// 'zh-Hans-CN'
```
---
#### `languages`
定义: `get languages(): readonly Intl.BCP47LanguageTag[]`
描述: 返回当前可用语言的[`BCP47 Language Tag`](https://www.techonthenet.com/js/language_tags.php)数组，可利用该方法作为切换语言下拉框的数据源
用例:
```ts
console.log(l10n.languages)
// ['zh-Hans-CN', 'en-US']
```
---
#### `direction`
定义: `direction(language?: Intl.BCP47LanguageTag): TextInfoDirection`
描述: 绝大多数语言都尊崇从左到右的阅读习惯，但某些语言却例外比如阿拉伯语，此方法可以得知所传入语言的[TextInfoDirection](#textinfodirection)
用例:
```ts
console.log(l10n.direction('ar'))
// 'rtl'
```
---
#### `on`
定义: `on(event: L10nListenEvent, callback: (...args: any[]) => void)`
描述: 用于注册[l10n](#l10n)的[L10nListenEvent](#l10nlistenevent)事件回调，比如`languageChanged`
用例:
```ts
l10n.on(L10nListenEvent.languageChanged, (...args: any[]) => {
//在切换语言后的一些操作，某些数据可以放在这里持久化，之后便会重启整个游戏场景
})
```
---
#### `off`
定义: `off(event: L10nListenEvent, callback: (...args: any[]) => void)`
描述: 用于反注册[l10n](#l10n)的[L10nListenEvent](#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) | 否 |
---
## `ResourceData`
| 函数/变量名 | 类型 | 可选 |
|-----------------------|---------------------------------|-----|
| `[namespace: string]` | [`ResourceItem`](#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` |