國際化

lh-ui-plus 內建國際化支援，提供中文（zh-CN）和英文（en-US）雙語包。支援執行時切換、自訂語言包和按需載入。

全域設定

透過 LhConfigProvider 的 locale prop 設定全域語言。

Composition API

<script setup lang="ts">
import { ref, computed } from 'vue'
import { LhConfigProvider, LhInput, LhButton, zhCN, enUS } from '@lh-ui/vue3'

const locale = ref('zh-CN')
const messages = computed(() => locale.value === 'zh-CN' ? zhCN : enUS)
</script>

<template>
  <LhConfigProvider :locale="messages">
    <LhInput placeholder="请输入内容" />
    <LhButton @click="locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN'">
      切换语言
    </LhButton>
  </LhConfigProvider>
</template>

Options API

<script>
import { LhConfigProvider, LhInput, LhButton, zhCN, enUS } from '@lh-ui/vue3'

export default {
  data() {
    return { locale: 'zh-CN' }
  },
  methods: {
    toggleLocale() {
      this.locale = this.locale === 'zh-CN' ? 'en-US' : 'zh-CN'
    },
  },
}
</script>

<template>
  <LhConfigProvider :locale="locale === 'zh-CN' ? zhCN : enUS">
    <LhInput placeholder="请输入内容" />
    <LhButton @click="toggleLocale">切换语言</LhButton>
  </LhConfigProvider>
</template>

使用 lhlocale API

lhlocale 是全域語言實例，提供單例 API，適用於跨元件語言切換。

Composition API

<script setup lang="ts">
import { ref, computed } from 'vue'
import { lhlocale, zhCN, enUS } from '@lh-ui/vue3'

const locale = ref('zh-CN')

function toggle() {
  const next = locale.value === 'zh-CN' ? 'en-US' : 'zh-CN'
  lhlocale.use({ locale: next, messages: next === 'zh-CN' ? zhCN : enUS })
  locale.value = next
}

const placeholder = computed(() => lhlocale.t('input.placeholder'))
</script>

<template>
  <LhInput :placeholder="placeholder" />
  <LhButton @click="toggle">切换语言</LhButton>
</template>

Options API

<script>
import { lhlocale, zhCN, enUS } from '@lh-ui/vue3'

export default {
  data() {
    return { locale: 'zh-CN' }
  },
  computed: {
    placeholder() {
      return lhlocale.t('input.placeholder')
    },
  },
  methods: {
    toggle() {
      const next = this.locale === 'zh-CN' ? 'en-US' : 'zh-CN'
      lhlocale.use({ locale: next, messages: next === 'zh-CN' ? zhCN : enUS })
      this.locale = next
    },
  },
}
</script>

<template>
  <LhInput :placeholder="placeholder" />
  <LhButton @click="toggle">切换语言</LhButton>
</template>

語言包結構

語言包遵循點號分隔鍵路徑，層級與元件模組對應：

// zh-CN.ts
export default {
  common: { loading: '加載中' },
  input: { placeholder: '請輸入', password: '密碼' },
  select: { placeholder: '請選擇', noMatch: '無匹配數據', noData: '暫無數據' },
  form: { validateFailed: '校驗失敗', required: '此項為必填' },
  datepicker: { now: '此刻', today: '今天', cancel: '取消', confirm: '確定' },
  timepicker: { now: '此刻', confirm: '確定', cancel: '取消' },
  cascader: { placeholder: '請選擇', noMatch: '無匹配數據' },
  dialog: { close: '關閉對話框' },
  // ... 更多元件語言
}

自訂語言包

新增語言

import { lhlocale } from '@lh-ui/vue3'

const jaJP = {
  input: { placeholder: '入力してください', password: 'パスワード' },
  select: { placeholder: '選択してください', noMatch: '該當なし', noData: 'データなし' },
  form: { validateFailed: '検証失敗', required: '必須アイテムです' },
}

// 註冊為 'ja-JP'
lhlocale.add('ja-JP', jaJP)
lhlocale.setLocale('ja-JP')

覆寫預設翻譯

import { lhlocale, zhCN } from '@lh-ui/vue3'

const customZh = {
  ...zhCN,
  input: {
    placeholder: '自定義佔位符',
    password: '密碼',
  },
}

lhlocale.use({ locale: 'zh-CN', messages: customZh })

響應式狀態

元件使用 lhlocale.version 實現響應式更新。語言切換時 version 自動遞增，觸發依賴該值的 computed 重新計算。

Composition API

<script setup lang="ts">
import { computed } from 'vue'
import { lhlocale } from '@lh-ui/vue3'

const t = (path: string) => lhlocale.t(path)
const currentLocale = computed(() => lhlocale.getLocale())
</script>

Options API

<script>
import { lhlocale } from '@lh-ui/vue3'

export default {
  computed: {
    currentLocale() {
      return lhlocale.getLocale()
    },
  },
  methods: {
    t(path) {
      return lhlocale.t(path)
    },
  },
}
</script>

最佳實踐

1. 優先使用 LhConfigProvider — 這是最推薦的方式，透過 locale prop 傳遞，所有子元件自動使用
2. 語言包完整對齊 — 新增語言包時，確保覆蓋所有元件的關鍵文案
3. 避免硬編碼 — 將使用者可見文字放入語言包，使用 lhlocale.t() 動態取得
4. 預設語言 — 專案預設語言為 zh-CN（透過 LH_LANGUAGE_DEFAULT 常數定義）