刘宇飞
d393302388
Adds level prefabs, theme assets, audio, extensions, and deployment scripts for the Unity WebGL migration. Co-authored-by: Cursor <cursoragent@cursor.com>
352 lines
9.2 KiB
Markdown
352 lines
9.2 KiB
Markdown
# 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` |
|