国际化 (i18n)

Directix 为指令消息、错误消息和帮助文本提供内置的国际化支持。

支持的语言

语言	代码	状态
中文	zh-CN	✅ 完整
英文	en-US	✅ 完整
日文	ja-JP	✅ 完整

基本用法

import { createI18n, setLocale, getLocale } from 'directix'
import { zhCN, enUS, jaJP } from 'directix'

// 初始化 i18n
const i18n = createI18n({
  locale: 'zh-CN',
  fallbackLocale: 'en-US',
  messages: {
    'zh-CN': zhCN,
    'en-US': enUS,
    'ja-JP': jaJP,
  },
})

// 运行时切换语言
setLocale('en-US')

// 获取当前语言
const currentLocale = getLocale() // 'en-US'

翻译键

所有指令消息遵循一致的键结构：

directives.{指令名称}.{消息类型}
errors.{错误键}
warnings.{警告键}
help.{帮助键}

示例键

键	描述
directives.debounce.description	防抖指令描述
directives.debounce.params.wait	"wait" 参数描述
directives.debounce.errors.invalid_wait	"wait" 参数无效错误消息
errors.invalid_param	通用参数无效错误
warnings.deprecated	功能已弃用警告

与警告系统配合使用

警告系统自动使用 i18n 翻译：

import { directiveWarn, setWarningI18n } from 'directix'
import { t } from 'directix'

// 将 i18n 连接到警告系统
setWarningI18n(t)

// 现在警告使用翻译后的消息
directiveWarn('debounce', 'errors.invalid_wait', { wait: -100 })
// 输出: [Directix] v-debounce: wait 参数无效，必须为正数

添加自定义语言

您可以添加自己的语言翻译：

import { createI18n, type I18nMessages } from 'directix'

const customLang: I18nMessages = {
  directives: {
    debounce: {
      description: '您的自定义描述',
      params: { wait: '您的自定义参数描述' },
      errors: { invalid_wait: '您的自定义错误消息' },
    },
    // ... 其他指令
  },
  errors: {
    invalid_param: '您的自定义错误',
    // ... 其他错误
  },
  warnings: {
    deprecated: '您的自定义警告',
    // ... 其他警告
  },
  help: {
    installation: '您的自定义帮助',
  },
}

createI18n({
  locale: 'custom',
  messages: { custom: customLang },
})

消息插值

消息支持参数插值：

import { t } from 'directix'

// 插值参数
const message = t('errors.type_error', {
  param: 'wait',
  expected: 'number',
  actual: 'string',
})
// 结果: "参数 'wait' 类型错误：期望 number，实际 string"

最佳实践

1. 尽早初始化 - 在使用指令前设置 i18n
2. 使用 fallbackLocale - 始终提供回退语言
3. 复用翻译 - 使用 t() 函数保持消息一致性
4. 谨慎扩展 - 添加自定义翻译时，扩展现有翻译

时区与地区适配

Directix 提供时区和地区适配工具，用于处理区域特定的格式化需求。

获取时区信息

import { getTimezoneInfo } from 'directix'

const tz = getTimezoneInfo()
console.log(tz)
// {
//   id: 'Asia/Shanghai',
//   offset: 8,
//   offsetString: '+08:00',
//   isDST: false,
//   name: 'Shanghai'
// }

检测用户地区

import { detectLocaleInfo } from 'directix'

const info = detectLocaleInfo()
console.log(info)
// {
//   locale: 'zh-CN',
//   language: 'zh',
//   region: 'CN',
//   script: null,
//   browserLocale: 'zh-CN',
//   timezone: 'Asia/Shanghai'
// }

地区特定日期格式

import { getDateFormat, formatDateLocale } from 'directix'

// 获取地区特定的日期格式配置
const dateFormat = getDateFormat('CN')
// {
//   datePattern: 'YYYY-MM-DD',
//   timePattern: 'HH:mm:ss',
//   hourCycle: 'h23',
//   firstDayOfWeek: 1,
//   dateSeparator: '-',
//   timeSeparator: ':'
// }

// 按地区格式化日期
const formatted = formatDateLocale(new Date())
// 输出根据用户地区自动格式化的日期时间

地区特定数字格式

import { getNumberFormat, formatNumberLocale, formatCurrencyLocale } from 'directix'

// 获取地区特定的数字格式配置
const numberFormat = getNumberFormat('DE')
// {
//   decimalSeparator: ',',
//   thousandsSeparator: '.',
//   currencySymbol: '€',
//   currencyPosition: 'after',
//   currencyDecimals: 2
// }

// 格式化数字
formatNumberLocale(1234567.89) // '1,234,567.89' (美国) 或 '1.234.567,89' (德国)

// 格式化货币
formatCurrencyLocale(99.99) // '$99.99' (美国) 或 '99,99€' (德国)

支持的地区

Directix 内置以下地区的格式化配置：

地区	代码	日期格式	货币符号
中国	CN	YYYY-MM-DD	¥
美国	US	MM/DD/YYYY	$
日本	JP	YYYY/MM/DD	¥
德国	DE	DD.MM.YYYY	€
法国	FR	DD/MM/YYYY	€
英国	GB	DD/MM/YYYY	£
韩国	KR	YYYY.MM.DD	₩
印度	IN	DD/MM/YYYY	₹

获取支持地区列表

import { getSupportedRegions } from 'directix'

const regions = getSupportedRegions()
// ['CN', 'US', 'JP', 'DE', 'FR', 'GB', 'KR', 'IN']

显示语言名称

import { getLocaleDisplayName } from 'directix'

// 获取语言的本地化显示名称
getLocaleDisplayName('zh-CN', 'en') // 'Chinese (China)'
getLocaleDisplayName('en-US', 'zh') // '英语（美国）'