@djangocfg/i18n

Lightweight, type-safe i18n library for @djangocfg packages.

Features

• 17 languages — en, ru, ko, ja, de, fr, zh, it, es, nl, ar, tr, pt-BR, pl, sv, no, da
• Type-safe — Full TypeScript support with autocomplete
• CLI included — Manage locales from the terminal
• Works standalone — Components work without provider

Installation

pnpm add @djangocfg/i18n

Quick Start

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

<I18nProvider locale="ru" translations={ru}>
  <App />
</I18nProvider>

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

Subpath Imports (Server Components)

// ✅ Server-safe (no React Context)
import { en, ru, ko } from '@djangocfg/i18n/locales'
import { mergeTranslations } from '@djangocfg/i18n/utils'

// ❌ Client-only (has React Context)
import { I18nProvider, useT } from '@djangocfg/i18n'

| Path | Description | |------|-------------| | @djangocfg/i18n | Full package (client components) | | @djangocfg/i18n/locales | Locale data only (server-safe) | | @djangocfg/i18n/utils | Utilities like mergeTranslations (server-safe) |

CLI

# Check missing keys across locales
pnpm i18n check

# List / search keys
pnpm i18n list
pnpm i18n list tour        # filter by pattern
pnpm i18n list -v          # with values

# Add key to all locales at once
pnpm i18n add "tools.new" '{"en":"New","ru":"Новый"}'

# Work with app locales in another directory
pnpm i18n check -d ../../apps/hub/i18n/locales
pnpm i18n list -d ../../apps/hub/i18n/locales

Hooks

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

useT()

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

useI18n()

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>
    </select>
  )
}

Type-safe next-intl Integration

Override useTranslations in your app's global.d.ts to get compile-time key validation.

// global.d.ts
type _Messages = import('@djangocfg/i18n').I18nTranslations &
  import('./i18n/locales/types').AppTranslations;

type _NSKeys = import('@djangocfg/i18n').NamespaceKeys<
  _Messages,
  import('@djangocfg/i18n').NestedKeyOf<_Messages>
>;

declare module 'next-intl' {
  export function useTranslations<NS extends _NSKeys>(
    namespace: NS,
  ): import('@djangocfg/i18n').IntlTranslator<_Messages, NS>;
}

Extending Translations

// Spread merge (recommended for next-intl)
import { en as baseEn } from '@djangocfg/i18n/locales'
const messages = { ...baseEn, ...appEn }

// Deep merge with overrides
import { mergeTranslations, ru } from '@djangocfg/i18n'
const customRu = mergeTranslations(ru, {
  ui: { select: { placeholder: 'Выберите...' } },
})

Interpolation

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

Translation Key Paths

ui.*         - UI components (select, form, dialog, table, pagination)
layouts.*    - Layout components (sidebar, auth, profile, theme)
api.*        - API/network messages
centrifugo.* - WebSocket monitoring
tools.*      - Heavy tools (tour, upload, code, image)

Works Without Provider

Components using useT() fall back to English defaults when used outside a provider.

License

MIT