@djangocfg/i18n

Lightweight, type-safe i18n library for @djangocfg component packages. Provides built-in translations for English, Russian, and Korean with easy extensibility.

Features

• Type-safe - Full TypeScript support with autocomplete for translation keys
• Lightweight - No heavy dependencies, pure React
• Extensible - Easy to add custom translations or override defaults
• Works standalone - Components work without provider using English defaults
• 3 languages built-in - English, Russian, Korean

Installation

pnpm add @djangocfg/i18n

Quick Start

import { I18nProvider, useT, ru } from '@djangocfg/i18n'

// Wrap your app (optional - works without provider too)
<I18nProvider locale="ru" translations={ru}>
  <App />
</I18nProvider>

// Use in components - simplest way
function MyComponent() {
  const t = useT()
  return <span>{t('ui.form.save')}</span>
}

Hooks

| Hook | Description | |------|-------------| | useT() | Returns translation function, works with/without provider (recommended) | | useI18n() | Full context: { t, locale, setLocale, translations } | | useTranslation() | Alias for useT() | | useLocale() | Returns current locale string | | useTypedT<T>() | Type-safe translation function with compile-time key validation |

useT() - Recommended

function MyComponent() {
  const t = useT()
  return <button>{t('ui.form.save')}</button>
}

useI18n() - Full Context

function LocaleSwitcher() {
  const { t, locale, setLocale } = useI18n()

  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value)}>
      <option value="en">English</option>
      <option value="ru">Russian</option>
      <option value="ko">Korean</option>
    </select>
  )
}

useTypedT() - Type-Safe Keys

import { useTypedT } from '@djangocfg/i18n'
import type { I18nTranslations } from '@djangocfg/i18n'

function MyComponent() {
  const t = useTypedT<I18nTranslations>()
  return <span>{t('ui.form.save')}</span>  // OK
  // t('ui.form.typo')  // Compile error!
}

getT() - Non-Hook Context

For class components or outside React:

import { getT } from '@djangocfg/i18n'

const label = getT('ui.form.save')
const message = getT('ui.pagination.showing', { from: 1, to: 10, total: 100 })

Extending Translations

mergeTranslations()

Deep merge base translations with custom overrides. Supports generic type parameter for app-specific namespaces:

import { mergeTranslations, ru } from '@djangocfg/i18n'

// Override specific keys
const customRu = mergeTranslations(ru, {
  ui: {
    select: { placeholder: 'Выберите марку авто...' }
  }
})

// Add app-specific namespace with type safety
type AppNamespace = { app: { title: string; welcome: string } }

const appRu = mergeTranslations<AppNamespace>(ru, {
  app: {
    title: 'Мое приложение',
    welcome: 'Добро пожаловать!'
  }
})
// Result type: I18nTranslations & AppNamespace

createTranslations()

Create translations from multiple partial sources:

import { createTranslations, en } from '@djangocfg/i18n'

const translations = createTranslations(
  en,              // base
  uiOverrides,     // UI customizations
  appStrings       // App-specific strings
)

Built-in Locales

import { en, ru, ko } from '@djangocfg/i18n'

• en - English (default)
• ru - Russian
• ko - Korean

Interpolation

t('ui.pagination.showing', { from: 1, to: 10, total: 100 })
// => "1-10 of 100"

t('ui.select.moreItems', { count: 5 })
// => "+5 more"

Type Utilities

import type { PathKeys, I18nKeys, I18nTranslations } from '@djangocfg/i18n'

// Get all valid keys from any translations type
type MyKeys = PathKeys<MyTranslations>
// = "form.title" | "form.submit" | "messages.error" | ...

// Built-in keys for base translations
const key: I18nKeys = 'ui.form.save'  // OK
const bad: I18nKeys = 'ui.form.typo'  // Error

Translation Key Paths

All translation keys use dot notation:

UI Components

ui.select.placeholder      - "Select option..."
ui.select.search           - "Search..."
ui.select.noResults        - "No results found."
ui.select.selectAll        - "Select all"
ui.select.clearAll         - "Clear all"
ui.select.moreItems        - "+{count} more"

ui.pagination.previous     - "Previous"
ui.pagination.next         - "Next"
ui.pagination.showing      - "{from}-{to} of {total}"

ui.form.submit             - "Submit"
ui.form.save               - "Save"
ui.form.cancel             - "Cancel"
ui.form.delete             - "Delete"
ui.form.loading            - "Loading..."
ui.form.required           - "This field is required"

ui.dialog.close            - "Close"
ui.dialog.confirm          - "Confirm"

ui.errors.generic          - "Something went wrong"
ui.errors.network          - "Network error..."

Layouts

layouts.sidebar.toggle     - "Toggle sidebar"
layouts.profile.settings   - "Settings"
layouts.profile.logout     - "Log out"
layouts.theme.light        - "Light"
layouts.theme.dark         - "Dark"

API

api.errors.networkError    - "Network error"
api.status.connecting      - "Connecting..."
api.status.connected       - "Connected"

Works Without Provider

Components using useT() or useI18n() work without provider - they fall back to English defaults. This allows gradual adoption in existing projects.

Integration with @djangocfg packages

This package is designed to work with:

• @djangocfg/ui-core - Base React components
• @djangocfg/ui-nextjs - Next.js specific components
• @djangocfg/layouts - Layout components
• @djangocfg/nextjs - Next.js App Router integration with next-intl

License

MIT