Language and Currency Configuration Guide

This document explains how to add or modify supported languages and currencies in the system.

Language Configuration

Modify Language Settings File

File location: src/i18n/settings.ts

// 1. Modify default language (optional)
export const fallbackLng = 'en' // Default language code

// 2. Add new language to supported list
export const languages = [fallbackLng, 'zh-CN', 'ja', 'ko'] // Adding Korean example

// 3. Update language selection mapping
export const languagesSelectMap = {
  'en': { name: 'English', short: 'EN' },
  'zh-CN': { name: '中文', short: '中' },
  'ja': { name: '日本語', short: '日' },
  'ko': { name: '한국어', short: '한' } // Adding Korean example
}

Update Utility Functions

File location: src/lib/utils.ts

Update Currency-Language Mapping

Add new mapping in getCurrencyLang() function:

export function getCurrencyLang(currency: string): string {
  const currencyLangMap: Record<string, string> = {
    'usd': 'en',
    'cny': 'zh-CN',
    'jpy': 'ja',
    'krw': 'ko', // Add Korean Won to Korean
  }
  return currencyLangMap[currency.toLowerCase()] || 'en'
}

Update Price Formatting Function

Add new language locale mapping in formatPrice() function:

export function formatPrice(price: number, currency: string, lang: string = 'en'): string {
  // Add new language locale mapping
  const locale = lang === 'zh-CN' ? 'zh-CN'
    : lang === 'ja' ? 'ja-JP'
    : lang === 'ko' ? 'ko-KR' // Add Korean
    : 'en-US'
  
  const formatter = new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: currency.toUpperCase(),
    minimumFractionDigits: 0,
    maximumFractionDigits: 2,
    currencyDisplay: 'narrowSymbol',
  })
  return formatter.format(price / 100)
}

Currency Configuration

Update System Settings Page

File location: src/app/[lang]/admin/system/settings/page.tsx

Update Default Currency Setting

Modify default currency in defaultSettings:

const defaultSettings: SystemSettings = {
  // ... other settings
  defaultCurrency: 'usd', // Modify default currency
}

Add Currency Options

Add new currency options in language settings section:

<div>
  <Label htmlFor="defaultCurrency">{t('system.defaultCurrency')}</Label>
  <Select value={settings.defaultCurrency} onValueChange={(value) => handleChange('defaultCurrency', value)}>
    <SelectTrigger>
      <SelectValue />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="usd">{t('system.currencyUSD')}</SelectItem>
      <SelectItem value="cny">{t('system.currencyCNY')}</SelectItem>
      <SelectItem value="jpy">{t('system.currencyJPY')}</SelectItem>
      <SelectItem value="krw">{t('system.currencyKRW')}</SelectItem>
    </SelectContent>
  </Select>
</div>

Update SEO Default Settings

Add SEO defaults for new language in defaultSEOSettings:

const defaultSEOSettings: SEOSettings = {
  // ...
  localized: {
    'en': { /* ... */ },
    'zh-CN': { /* ... */ },
    'ja': { /* ... */ },
    'ko': {
      siteName: 'Hex2077 Starter',
      siteDescription: '최고의 SaaS 템플릿.',
      siteKeywords: 'hex2077,starter,saas,템플릿'
    } // Add new language SEO default config
  }
}

Multilingual Files

Create Translation Files for New Language

Create complete translation file directory for each new language:

public/locales/ko/
├── admin.json
├── auth.json
├── common.json
├── credits.json
├── email.json
├── home.json
├── privacy.json
├── profile.json
├── refund.json
├── subscription.json
├── terms.json
└── user.json

Add language and currency related translation keys in admin.json:

{
  "system": {
    "language": "Language",
    "languageChinese": "Chinese",
    "languageEnglish": "English",
    "languageJapanese": "Japanese",
    "languageKorean": "Korean",
    "defaultCurrency": "Default Currency",
    "currencyUSD": "US Dollar (USD)",
    "currencyCNY": "Chinese Yuan (CNY)",
    "currencyJPY": "Japanese Yen (JPY)",
    "currencyKRW": "Korean Won (KRW)"
  }
}

Complete Example: Adding Korean and KRW Support

Step 1: Modify `src/i18n/settings.ts`

export const fallbackLng = 'en'
export const languages = [fallbackLng, 'zh-CN', 'ja', 'ko']
export const defaultNS = 'common'

export const languagesSelectMap = {
  'en': { name: 'English', short: 'EN' },
  'zh-CN': { name: '中文', short: '中' },
  'ja': { name: '日本語', short: '日' },
  'ko': { name: '한국어', short: '한' }
}

Step 2: Modify `src/lib/utils.ts`

// Update currency-language mapping
export function getCurrencyLang(currency: string): string {
  const currencyLangMap: Record<string, string> = {
    'usd': 'en',
    'cny': 'zh-CN',
    'jpy': 'ja',
    'krw': 'ko',
  }
  return currencyLangMap[currency.toLowerCase()] || 'en'
}

// Update price formatting
export function formatPrice(price: number, currency: string, lang: string = 'en'): string {
  const locale = lang === 'zh-CN' ? 'zh-CN' 
    : lang === 'ja' ? 'ja-JP' 
    : lang === 'ko' ? 'ko-KR'
    : 'en-US'
  
  const formatter = new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: currency.toUpperCase(),
    minimumFractionDigits: 0,
    maximumFractionDigits: 2,
    currencyDisplay: 'narrowSymbol',
  })
  return formatter.format(price / 100)
}

Step 3: Create Translation Files

Create public/locales/ko/ directory with all required JSON files and add corresponding Korean translations.

Step 4: Update admin.json for All Languages

Add to each language's admin.json:

{
  "system": {
    "languageKorean": "Korean",
    "currencyKRW": "Korean Won (KRW)"
  }
}

Important Notes

Language Code Standards

Use standard BCP 47 language tags
Examples: en (English), zh-CN (Simplified Chinese), ja (Japanese), ko (Korean)

Currency Code Standards

Use ISO 4217 standard three-letter currency codes
Examples: USD (US Dollar), CNY (Chinese Yuan), JPY (Japanese Yen), KRW (Korean Won)

Price Formatting

Prices stored in cents (integers)
Use Intl.NumberFormat for localized formatting
Different currencies may have different decimal place requirements

Translation File Completeness

Ensure all language translation files have consistent structure
When adding new translation keys, add to all language files
Missing translation keys fall back to default language

Testing Recommendations

Test language switching functionality
Test currency display format
Test price calculation and display
Test multilingual content correctness

FAQ

Q: How to change default language?

A: Modify the fallbackLng value in src/i18n/settings.ts.

Q: How to add unsupported currency?

A: As long as it's an ISO 4217 standard currency code, Intl.NumberFormat handles it automatically. Just add the option in system settings page.

Q: What if price formatting is incorrect?

A: Check if locale mapping in formatPrice() function is correct, ensure using the correct locale code.

Q: How to batch update all translation files?

A: Recommend using scripts or tools to manage translation files, ensuring all language files maintain consistent key-value pairs.