Internationalization (i18n)

Directix provides built-in internationalization support for directive messages, error messages, and help text.

Supported Languages

Language	Code	Status
Chinese	zh-CN	✅ Complete
English	en-US	✅ Complete
Japanese	ja-JP	✅ Complete

Basic Usage

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

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

// Switch locale at runtime
setLocale('en-US')

// Get current locale
const currentLocale = getLocale() // 'en-US'

Translation Keys

All directive messages follow a consistent key structure:

directives.{directiveName}.{messageType}
errors.{errorKey}
warnings.{warningKey}
help.{helpKey}

Example Keys

Key	Description
directives.debounce.description	Debounce directive description
directives.debounce.params.wait	"wait" parameter description
directives.debounce.errors.invalid_wait	Invalid "wait" error message
errors.invalid_param	Generic invalid parameter error
warnings.deprecated	Deprecated feature warning

Using with Warnings

The warning system automatically uses i18n translations:

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

// Connect i18n to warning system
setWarningI18n(t)

// Now warnings use translated messages
directiveWarn('debounce', 'errors.invalid_wait', { wait: -100 })
// Output: [Directix] v-debounce: Invalid "wait" parameter, must be a positive number

Adding Custom Languages

You can add your own language translations:

import { createI18n, type I18nMessages } from 'directix'

const customLang: I18nMessages = {
  directives: {
    debounce: {
      description: 'Your custom description',
      params: { wait: 'Your custom param description' },
      errors: { invalid_wait: 'Your custom error message' },
    },
    // ... other directives
  },
  errors: {
    invalid_param: 'Your custom error',
    // ... other errors
  },
  warnings: {
    deprecated: 'Your custom warning',
    // ... other warnings
  },
  help: {
    installation: 'Your custom help',
  },
}

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

Message Interpolation

Messages support parameter interpolation:

import { t } from 'directix'

// Interpolate parameters
const message = t('errors.type_error', {
  param: 'wait',
  expected: 'number',
  actual: 'string',
})
// Result: "Type error for parameter 'wait': expected number, got string"

Best Practices

1. Initialize early - Set up i18n before using directives
2. Use fallbackLocale - Always provide a fallback language
3. Reuse translations - Use t() function for consistent messaging
4. Extend carefully - When adding custom translations, extend existing ones

Timezone and Locale Adaptation

Directix provides timezone and locale utilities for handling region-specific formatting.

Getting Timezone Info

import { getTimezoneInfo } from 'directix'

const tz = getTimezoneInfo()
console.log(tz)
// {
//   id: 'America/New_York',
//   offset: -5,
//   offsetString: '-05:00',
//   isDST: false,
//   name: 'New York'
// }

Detecting User Locale

import { detectLocaleInfo } from 'directix'

const info = detectLocaleInfo()
console.log(info)
// {
//   locale: 'en-US',
//   language: 'en',
//   region: 'US',
//   script: null,
//   browserLocale: 'en-US',
//   timezone: 'America/New_York'
// }

Region-Specific Date Formatting

import { getDateFormat, formatDateLocale } from 'directix'

// Get region-specific date format config
const dateFormat = getDateFormat('US')
// {
//   datePattern: 'MM/DD/YYYY',
//   timePattern: 'hh:mm:ss a',
//   hourCycle: 'h12',
//   firstDayOfWeek: 0,
//   dateSeparator: '/',
//   timeSeparator: ':'
// }

// Format date according to region
const formatted = formatDateLocale(new Date())
// Output varies based on user's locale

Region-Specific Number Formatting

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

// Get region-specific number format config
const numberFormat = getNumberFormat('DE')
// {
//   decimalSeparator: ',',
//   thousandsSeparator: '.',
//   currencySymbol: '€',
//   currencyPosition: 'after',
//   currencyDecimals: 2
// }

// Format numbers
formatNumberLocale(1234567.89) // '1,234,567.89' (US) or '1.234.567,89' (DE)

// Format currency
formatCurrencyLocale(99.99) // '$99.99' (US) or '99,99€' (DE)

Supported Regions

Directix includes built-in formatting configs for these regions:

Region	Code	Date Format	Currency
China	CN	YYYY-MM-DD	¥
United States	US	MM/DD/YYYY	$
Japan	JP	YYYY/MM/DD	¥
Germany	DE	DD.MM.YYYY	€
France	FR	DD/MM/YYYY	€
United Kingdom	GB	DD/MM/YYYY	£
South Korea	KR	YYYY.MM.DD	₩
India	IN	DD/MM/YYYY	₹

Getting Supported Regions

import { getSupportedRegions } from 'directix'

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

Displaying Language Names

import { getLocaleDisplayName } from 'directix'

// Get localized display name for a language
getLocaleDisplayName('zh-CN', 'en') // 'Chinese (China)'
getLocaleDisplayName('en-US', 'zh') // '英语（美国）'