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

8.6 KiB
Raw Blame History

Localization Editor Api

Quick Start

Core Features l10n

l10n provides the core translation function and icu function, as well as the function to switch languages.

We will store the switched target language in localStorage and also automatically restart the project runtime and read the localStorage configuration at the next start to complete the whole language switching process.

So we want users to make sure to handle data persistence before switching languages

Import the l10n module

All api's provided by localization-editor will be imported by name from db://localization-editor/l10n

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

Use the translation api

// in the code of any component component

// l10n is the core functionality of localization
import { l10n } from 'db://localization-editor/l10n'
import { _decorator, Label, Component } from 'cc';

@ccclass('SomeComponent')
class SomeComponent extends Component {
    // ......
    someMethod() {
        // will return the text corresponding to this_is_an_apple
        const text = l10n.t("this_is_an_apple")
    }
    // ......
}

API details

  • Alias:[L10nKey](#alternate name)

  • Alias:L10nValue

  • Alias:[TextInfoDirection](# alias)

  • Alias:[FallbackLanguage](# alias)

L10nManager

Import example.

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

Description.

Normally we do not recommend that you use or construct this type yourself.

Instead, we provide l10n as a global singleton to use the translation functionality.

Index

Constructor

  • L10nManager private

Global variables

l10n

Definition: const l10n: L10nManager

Static properties

LOCAL_STORAGE_LANGUAGE_KEY

Definition: static LOCAL_STORAGE_LANGUAGE_KEY: string

Description: When calling changeLanguage to switch the game language, localStorage is used to and use LOCAL_STORAGE_LANGUAGE_KEY as the key of localStorage.

Remarks.

default localization-editor/language

Instance methods

config

Definition: config(options: L10nOptions): void

Description: Used to configure certain settings of l10n, see L10nOptions for more options.

Use case:

l10n.config({
    // Used to display the default language with this value if no translation is found
    fallbackLanguage: 'zh-Hans-CN',
    // If you don't like the default value of LOCAL_STORAGE_LANGUAGE_KEY, you can change it here, but make sure it's before changeLanguage
    localStorageLanguageKey: 'localization-editor/langauge'
})

changeLanguage

Definition: changeLanguage(language: Intl.BCP47LanguageTag): void

Description: Used to dynamically switch languages, see BCP47 Language Tag for more information

Use case:

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

Note: After calling this method, the game will be restarted automatically, please make sure to do the data persistence work

t

Definition: t(key: L10nKey, options?: StandardOption): L10nValue

Description: Returns the L10nValue corresponding to the current language data according to the incoming L10nKey, see StandardOption for more options.

Use case:

console.log(l10n.t('this_is_apple'))
// This is an apple

Note: The language data needs to be generated after compilation with the Localization Editor plugin.

Cannot use l10n.t in static initialization, e.g. static name = l10n.t('xxx_name')

Unable to scan when variable is used as parameter, e.g. let name = 'this_is_apple'; l10n.t(name)

exists

Definition: exists(key: L10nKey): boolean

Description: Returns whether the key exists or not

Use case:

console.log(l10n.exists('test_key'))

currentLanguage

Definition: get currentLanguage(): Intl.BCP47LanguageTag

Description: Returns the BCP47 Language Tag for the current language.

Use case:

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

languages

Definition: get languages(): readonly Intl.BCP47LanguageTag[]

Description: Returns an array of BCP47 Language Tag for the currently available languages, which can be used as a data source for switching language dropdown boxes

Use case:

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

direction

Definition: direction(language?: Intl. BCP47LanguageTag): TextInfoDirection

Description: Most languages respect the left-to-right reading convention, but some languages are exceptions such as Arabic, this method learns the TextInfoDirection of the incoming language.

Use case:

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

on

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

Description: Used to register L10nListenEvent event callbacks for l10n, such as languageChanged.

use case:

l10n.on(L10nListenEvent.languageChanged, (. .args: any[]) => {
    // some actions after switching language, some data can be persisted here and the whole game scene will be restarted afterwards
})

--

off

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

Description: Callback for the L10nListenEvent event used to counter-register l10n

Make sure to make on and off appear in pairs to ensure proper destruction of useless data

Alias

alias original type
L10nKey string
L10nValue string
TextInfoDirection 'ltr' / 'rtl'
FallbackLanguage string / readonly string[] / FallbackLanguageObjectList / ((language: Intl.BCP47LanguageTag) => string / readonly string[] / FallbackLanguageObjectList

Interface

L10nOptions

function/variable name type optional
fallbackLanguage false / [FallbackLanguage](# alias) yes
localStorageLanguageKey string yes
beforeTranslate (key: L10nKey) => L10nValue yes
afterTranslate (key: L10nKey) => L10nValue yes
returnNull boolean yes
returnEmptyString boolean yes

ResourceList

function/variable name type optional
defaultLanguage Intl.BCP47LanguageTag yes
fallbackLanguage Intl.BCP47LanguageTag yes
languages Intl.BCP47LanguageTag[] no

ResourceBundle

function/variable name type optional
[language: Intl.BCP47LanguageTag] ResourceData no

ResourceData

function/variable name type optional
[namespace: string] ResourceItem no

ResourceItem

function/variable name type optional
[key: string] any no

FallbackLanguageObjectList

function/variable name type optional
[language: string] readonly string[] no

StandardOption

function/variable name type optional
count number yes
defaultValue L10nValue yes
language Intl.BCP47LanguageTag yes
fallbackLanguage [FallbackLanguage](# alias) yes

Enumerations

L10nListenEvent

function/variable name type
languageChanged languageChanged
onMissingKey missingKey