国际化

xtf-linkui 内置中英文语言包，所有内置文案均通过国际化系统读取，业务侧可切换语言或注册自定义语言包。

实现文件：uni_modules/xtf-linkui/libs/locale/

---

语言包结构

语言包按组件/模块分目录组织，每个模块对应一组文案 key。内置两个语言包：

• zh-CN.js — 中文
• en-US.js — 英文

以 zh-CN.js 为例，结构如下：

export default {
  common: {
    confirm: '确认',
    cancel: '取消',
    pleaseSelect: '请选择',
    noData: '暂无数据',
    loading: '加载中...'
  },
  input: {
    placeholder: '请输入内容',
    fieldRequired: '该项不能为空'
  },
  dialog: {
    confirmText: '确定',
    cancelText: '取消',
    inputPlaceholder: '请输入内容'
  },
  search: {
    placeholder: '搜索商品、订单、用户',
    cancelText: '取消'
  },
  upload: {
    pickerText: '上传图片',
    retryText: '重试'
  },
  // ... 更多模块
}

覆盖的模块包括：common / input / select / picker / dialog / actionSheet / pullRefresh / infiniteScroll / datetimePicker / cascader / empty / result / list / pagination / search / virtualList / image / table / timeline / signature / grid / upload / shareSheet / calendar / countdown / formArray / form / dropdownItem / dropdownMenu / lazyload / numberKeyboard 等。

---

切换语言

通过 xtf-config-provider 的 locale 属性全局切换，推荐放在应用根节点：

<template>
  <xtf-config-provider locale="en-US">
    <router-view />
  </xtf-config-provider>
</template>

支持的内置语言：

locale	语言
zh-CN	简体中文（默认）
en-US	English

---

注册自定义语言包

通过 registerLocale 注册自定义语言包，支持完全自定义或覆盖部分 key：

import { registerLocale } from '@/uni_modules/xtf-linkui'

// 注册一种全新语言
registerLocale('ja-JP', {
  common: { confirm: '確認', cancel: 'キャンセル' },
  dialog: { confirmText: '確定' },
  search: { placeholder: '検索' }
})

// 在现有中文基础上覆盖某几个 key
import { zhCN, registerLocale } from '@/uni_modules/xtf-linkui'

registerLocale('zh-CN', {
  ...zhCN,
  common: {
    ...zhCN.common,
    confirm: '好的'
  }
})

注册后，将 xtf-config-provider 的 locale 设为对应值即可生效。

---

在组件内读取文案

组件内使用 getLocaleText

组件内部通过 getLocaleText(provider, path, fallback) 读取当前语言包文案：

import { getLocaleText } from '@/uni_modules/xtf-linkui'

// provider 为 xtfLocaleProvider（由 xtf-config-provider 注入）
const placeholder = getLocaleText(this.xtfLocaleProvider, 'search.placeholder', '搜索')

业务侧使用 useLocale

业务页面也可通过 useLocale 读取当前语言配置：

import { useLocale } from '@/uni_modules/xtf-linkui'

export default {
  mounted() {
    const locale = useLocale(this)
    console.log('当前语言:', locale.name)
    console.log('确认按钮文案:', locale.t('common.confirm'))
  }
}

useLocale 返回：

字段	说明
name	当前语言名，如 'zh-CN'
messages	当前完整语言包对象
t(path, fallback)	按路径读取文案，如 t('common.confirm')

---

自定义文案约定

• 语言包是纯 key: value 结构，支持对象嵌套（用 . 分隔路径）
• 部分文案支持占位符，例如 table.paginationSummary: '第 {start}-{end} 条，共 {total} 条'，由组件在运行时替换
• 业务自定义组件如需接入国际化，直接在 xtf-config-provider 下注入 xtfLocaleProvider，并使用 getLocaleText 读取即可