Language Management Module

A comprehensive internationalization and localization management module for DBS Portal, providing language detection, translation management, and locale switching capabilities.

Features

🌍 Language Detection

• Browser language detection from Accept-Language headers
• URL parameter-based language switching
• Cookie-based user preference storage
• Geolocation-based language suggestions
• Fallback language support

📝 Translation Management

• Hierarchical namespace organization
• Translation key management with metadata
• Multi-language translation editing
• Translation approval workflows
• Auto-translation integration
• Import/export capabilities (JSON, CSV, XLSX, PO, XLIFF)

🎨 UI Components

• LanguageList: Comprehensive language management interface
• LocaleSelector: Flexible language selection dropdown
• TranslationEditor: Multi-language translation editing interface

🔧 Developer Tools

• React Query hooks for data fetching
• TypeScript-first API with full type safety
• Zustand store integration
• i18next configuration utilities

Installation

npm install @dbs-portal/module-language-management

Dependencies

Required

• @tanstack/react-query - Data fetching and caching
• antd - UI components
• react - React framework
• i18next - Internationalization framework
• react-i18next - React bindings for i18next

Optional

• @dnd-kit/core - Drag and drop functionality
• @dnd-kit/sortable - Sortable lists
• @dnd-kit/utilities - DnD utilities
• i18next-browser-languagedetector - Browser language detection
• i18next-http-backend - HTTP backend for translations

Quick Start

1. Basic Setup

import { LanguageList, LocaleSelector } from '@dbs-portal/module-language-management'

function App() {
  return (
    <div>
      {/* Language selector in header */}
      <LocaleSelector 
        value="en"
        onChange={(lang) => console.log('Language changed:', lang)}
        showFlags
        showNativeNames
      />
      
      {/* Language management page */}
      <LanguageList 
        showStatistics
        onLanguageSelect={(lang) => console.log('Selected:', lang)}
      />
    </div>
  )
}

2. Using React Query Hooks

import { useLanguages, useTranslationKeys } from '@dbs-portal/module-language-management'

function LanguageManager() {
  const { data: languages, isLoading } = useLanguages()
  const { data: translations } = useTranslationKeys(1, 50, {
    namespaceId: 'common'
  })

  if (isLoading) return <div>Loading...</div>

  return (
    <div>
      <h2>Available Languages ({languages?.meta?.total})</h2>
      {languages?.data?.map(lang => (
        <div key={lang.code}>{lang.name}</div>
      ))}
    </div>
  )
}

3. Language Detection

import { detectLanguage, initializeI18n } from '@dbs-portal/module-language-management'

// Detect user's preferred language
const detection = detectLanguage({
  acceptLanguage: 'en-US,en;q=0.9,es;q=0.8',
  url: window.location.href,
  fallbackLanguage: 'en'
})

console.log('Detected language:', detection.detectedLanguage)
console.log('Confidence:', detection.confidence)

// Initialize i18n
await initializeI18n({
  defaultLanguage: detection.detectedLanguage,
  apiBaseUrl: '/api',
  enableBackend: true,
  enableDetection: true
})

API Reference

Components

LanguageList

Comprehensive language management interface with CRUD operations.

interface LanguageListProps {
  onLanguageSelect?: (language: Language) => void
  onLanguageToggle?: (language: Language, enabled: boolean) => void
  showStatistics?: boolean
  allowReorder?: boolean
  className?: string
}

LocaleSelector

Flexible language selection dropdown with multiple display modes.

interface LocaleSelectorProps {
  value?: LanguageCode
  onChange?: (language: LanguageCode) => void
  showFlags?: boolean
  showNativeNames?: boolean
  size?: 'small' | 'large'
  placement?: 'top' | 'bottom' | 'topLeft' | 'topCenter' | 'topRight' | 'bottomLeft' | 'bottomCenter' | 'bottomRight'
  className?: string
}

TranslationEditor

Multi-language translation editing interface with approval workflows.

interface TranslationEditorProps {
  namespaceId?: ID
  keyId?: ID
  language?: LanguageCode
  onSave?: (key: string, translations: Record<LanguageCode, string>) => void
  onCancel?: () => void
  showPreview?: boolean
  enableAutoTranslation?: boolean
  className?: string
}

Hooks

Language Management

• useLanguages() - Fetch paginated languages
• useLanguage(code) - Fetch single language
• useCreateLanguage() - Create new language
• useUpdateLanguage() - Update existing language
• useDeleteLanguage() - Delete language
• useToggleLanguage() - Enable/disable language

Translation Management

• useTranslationKeys() - Fetch translation keys
• useTranslationKey(id) - Fetch single translation key
• useUpdateTranslation() - Update translation value
• useAutoTranslate() - Auto-translate keys
• useImportTranslations() - Import translation files
• useExportTranslations() - Export translations

Utilities

Language Detection

// Detect from various sources
detectFromAcceptLanguage(header: string): LanguageCode[]
detectFromUserAgent(userAgent: string): LanguageCode[]
detectFromURL(url: string, paramName?: string): LanguageCode | null
detectFromCookie(cookieName?: string): LanguageCode | null

// Comprehensive detection
detectLanguage(options: DetectionOptions): LanguageDetectionResult

i18n Configuration

// Initialize i18n
initializeI18n(config?: I18nConfig): Promise<typeof i18n>

// Translation management
loadTranslations(language: LanguageCode, namespace: string): Promise<Record<string, any>>
changeLanguage(language: LanguageCode): Promise<void>
getTranslation(key: string, options?: TranslationOptions): string

Supported Languages

The module supports 37 languages out of the box:

• European: English, Spanish, French, German, Italian, Portuguese, Dutch, Swedish, Danish, Norwegian, Finnish, Polish, Czech, Hungarian, Romanian, Bulgarian, Croatian, Slovak, Slovenian, Estonian, Latvian, Lithuanian, Maltese, Irish, Welsh, Basque, Catalan, Galician
• Asian: Chinese (Simplified), Chinese (Traditional), Japanese, Korean, Hindi, Thai, Vietnamese
• Middle Eastern: Arabic
• Slavic: Russian

Configuration

Environment Variables

# API endpoints
VITE_API_BASE_URL=http://localhost:3000/api
VITE_TRANSLATIONS_ENDPOINT=/translations

# Language detection
VITE_DEFAULT_LANGUAGE=en
VITE_FALLBACK_LANGUAGE=en
VITE_ENABLE_AUTO_DETECTION=true

# Auto-translation
VITE_ENABLE_AUTO_TRANSLATION=true
VITE_AUTO_TRANSLATION_PROVIDER=google

TypeScript Configuration

{
  "compilerOptions": {
    "types": ["@dbs-portal/module-language-management"]
  }
}

Development

Building

npm run build

Testing

npm test

Type Checking

npm run type-check

Contributing

1. Follow the established patterns for hooks, components, and services
2. Ensure all new features have TypeScript types
3. Add tests for new functionality
4. Update documentation for API changes

License

MIT License - see LICENSE file for details.