i18n

The library ships with an internationalization scheme: language packs are organized by namespace, components read text via useLocale, and switching the language persists and is restored on the next launch. zh-CN and en-US are built in, and fr-FR can be imported on demand.

Language pack structure

Each language pack is an object that, besides the three identifier fields name / label / locale, groups the rest by namespace (e.g. uModal, uUpload):

export default {
    name: 'zh-CN',
    label: '简体中文',
    locale: 'zh-Hans',
    uModal: {
        title: '提示',
        confirmText: '确定',
        cancelText: '取消'
    },
    uSearch: {
        placeholder: '请输入关键字',
        actionText: '搜索'
    }
}

Field	Description
name	Language id, used for switching and persistence, e.g. zh-CN
label	Display name, shown in language lists, e.g. 简体中文
locale	Standard locale id, e.g. zh-Hans

Configure the locale

Configure it in main.uts via the locale option:

import uViewProX from './uni_modules/uview-pro-x'

app.use(uViewProX, {
    locale: {
        locales: [],            // language packs; empty means use built-in zh-CN / en-US
        defaultLocale: 'zh-CN', // default language
        isForce: false          // when true, defaultLocale takes top priority
    }
})

Field	Type	Description
locales	any[]	Language packs; when omitted or empty, built-in packs are used
defaultLocale	string	Default language name
isForce	boolean	When true, defaultLocale takes top priority and the saved choice is ignored

Using language packs

Read text with useLocale, preferring destructuring:

import { useLocale } from '@/uni_modules/uview-pro-x'

const { t, currentLocale, locales, setLocale } = useLocale()

// Look up by full path
t('uModal.title')

// Switch language (persisted)
setLocale('en-US')

Namespace

Passing a namespace to useLocale(namespace) makes t add the prefix automatically, avoiding repetition:

const { t } = useLocale('uSearch')

t('placeholder')        // same as t('uSearch.placeholder')

Placeholder replacement

Placeholders like {name} in the text can be replaced by passing an object as the second argument:

// In the pack: notAllowedExt: 'Files of type {ext} are not allowed'
t('uUpload.notAllowedExt', { ext: 'png' })

Custom language packs

When locales receives custom packs:

• Same-named language (e.g. another zh-CN) is deep-merged with the built-in pack: the fields you provide override the built-in ones, and the rest keep the built-in values.
• New language (e.g. ja-JP) is registered directly and appears in the locales list.

import uViewProX from './uni_modules/uview-pro-x'
import { frFR } from '@/uni_modules/uview-pro-x'

app.use(uViewProX, {
    locale: {
        locales: [frFR],        // merged with built-ins, adds French
        defaultLocale: 'fr-FR'
    }
})

Force override

By default a same-named language is deep-merged, overriding only the fields you write. To make the provided pack fully replace the built-in same-named pack, set isForce to true.

Locale resolution priority

On initialization, the default language is resolved in this order:

1. URL injection (H5): the lang parameter at the end of the link (e.g. ?lang=en-US), used to sync a demo page's language from the docs site iframe;
2. isForce is true: use defaultLocale;
3. Locally saved: the language the user switched to before;
4. defaultLocale: the fallback on first entry when not forced.

Notes

1. The language choice is persisted in local storage (key uview-pro-x-locale) and restored on the next launch.
2. When t(key) finds no match it returns the key as-is, making missing text easy to spot; switching languages never throws.
3. Namespaces are agreed by components; do not double up the prefix when calling t (after useLocale('uSearch') write t('placeholder'), not t('uSearch.placeholder')).
4. The lang injection on H5 works only on the WEB platform; other platforms always fall back to the regular resolution order.
5. isForce changes two things at once: a same-named pack goes from "deep-merge" to "full replace", and defaultLocale takes top priority during resolution (the saved choice is ignored).