@djangocfg/i18n 2.1.111

package/README.md

@@ -0,0 +1,235 @@
+# @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
+
+```bash
+pnpm add @djangocfg/i18n
+```
+
+## Quick Start
+
+```tsx
+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
+
+```tsx
+function MyComponent() {
+  const t = useT()
+  return <button>{t('ui.form.save')}</button>
+}
+```
+
+### useI18n() - Full Context
+
+```tsx
+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<T>() - Type-Safe Keys
+
+```tsx
+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:
+
+```tsx
+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:
+
+```tsx
+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:
+
+```tsx
+import { createTranslations, en } from '@djangocfg/i18n'
+
+const translations = createTranslations(
+  en,              // base
+  uiOverrides,     // UI customizations
+  appStrings       // App-specific strings
+)
+```
+
+## Built-in Locales
+
+```tsx
+import { en, ru, ko } from '@djangocfg/i18n'
+```
+
+- `en` - English (default)
+- `ru` - Russian
+- `ko` - Korean
+
+## Interpolation
+
+```tsx
+t('ui.pagination.showing', { from: 1, to: 10, total: 100 })
+// => "1-10 of 100"
+
+t('ui.select.moreItems', { count: 5 })
+// => "+5 more"
+```
+
+## Type Utilities
+
+```tsx
+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

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@djangocfg/i18n",
+  "version": "2.1.111",
+  "description": "Lightweight i18n library for @djangocfg packages with built-in translations for English, Russian, and Korean",
+  "keywords": [
+    "i18n",
+    "internationalization",
+    "localization",
+    "translations",
+    "react",
+    "nextjs",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "packages/i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/markolofsen/django-cfg/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
+    },
+    "./locales": {
+      "types": "./src/locales/index.ts",
+      "import": "./src/locales/index.ts",
+      "require": "./src/locales/index.ts"
+    },
+    "./locales/*": "./src/locales/*.ts",
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "import": "./src/utils/index.ts",
+      "require": "./src/utils/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@djangocfg/typescript-config": "^2.1.111",
+    "@types/react": "^19.1.0",
+    "eslint": "^9.37.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/context.tsx

@@ -0,0 +1,293 @@
+'use client'
+
+import * as React from 'react'
+
+import { en } from './locales/en'
+import type {
+  I18nContextValue,
+  I18nProviderProps,
+  I18nTranslations,
+  LocaleCode,
+} from './types'
+import { getNestedValue, interpolate, mergeTranslations } from './utils'
+
+/**
+ * I18n Context
+ */
+const I18nContext = React.createContext<I18nContextValue | null>(null)
+
+/**
+ * Default translations (English)
+ */
+const defaultTranslations: I18nTranslations = en
+
+/**
+ * I18n Provider
+ *
+ * @example
+ * // Basic usage with single locale
+ * import { I18nProvider, ru } from '@djangocfg/i18n'
+ *
+ * <I18nProvider locale="ru" translations={ru}>
+ *   <App />
+ * </I18nProvider>
+ *
+ * @example
+ * // With all translations for dynamic switching
+ * import { I18nProvider, en, ru, ko } from '@djangocfg/i18n'
+ *
+ * <I18nProvider
+ *   locale={currentLocale}
+ *   allTranslations={{ en, ru, ko }}
+ *   onLocaleChange={(locale) => setCurrentLocale(locale)}
+ * >
+ *   <App />
+ * </I18nProvider>
+ *
+ * @example
+ * // With custom overrides
+ * import { I18nProvider, ru, mergeTranslations } from '@djangocfg/i18n'
+ *
+ * const customRu = mergeTranslations(ru, {
+ *   ui: { select: { placeholder: 'Выберите марку...' } }
+ * })
+ *
+ * <I18nProvider locale="ru" translations={customRu}>
+ *   <App />
+ * </I18nProvider>
+ */
+export function I18nProvider({
+  children,
+  locale: initialLocale = 'en',
+  translations: initialTranslations,
+  allTranslations,
+  onLocaleChange,
+}: I18nProviderProps) {
+  const [locale, setLocaleState] = React.useState<LocaleCode>(initialLocale)
+
+  // Resolve current translations
+  const translations = React.useMemo<I18nTranslations>(() => {
+    // If allTranslations provided, use it to get translations for current locale
+    if (allTranslations && allTranslations[locale]) {
+      const localeTranslations = allTranslations[locale]
+      // Merge with defaults to fill any missing keys
+      return mergeTranslations(defaultTranslations, localeTranslations)
+    }
+
+    // If single translations provided, use them
+    if (initialTranslations) {
+      return mergeTranslations(
+        defaultTranslations,
+        initialTranslations as I18nTranslations
+      )
+    }
+
+    // Fallback to defaults
+    return defaultTranslations
+  }, [locale, allTranslations, initialTranslations])
+
+  // Translation function
+  const t = React.useCallback(
+    (key: string, params?: Record<string, string | number>): string => {
+      const value = getNestedValue(
+        translations as unknown as Record<string, unknown>,
+        key
+      )
+
+      if (value === undefined) {
+        // Development warning
+        if (typeof window !== 'undefined' && window.location.hostname === 'localhost') {
+          console.warn(`[i18n] Missing translation key: "${key}"`)
+        }
+        // Return the key as fallback
+        return key
+      }
+
+      return interpolate(value, params)
+    },
+    [translations]
+  )
+
+  // Locale change handler
+  const setLocale = React.useCallback(
+    (newLocale: LocaleCode) => {
+      setLocaleState(newLocale)
+      onLocaleChange?.(newLocale)
+    },
+    [onLocaleChange]
+  )
+
+  // Sync with external locale changes
+  React.useEffect(() => {
+    if (initialLocale !== locale) {
+      setLocaleState(initialLocale)
+    }
+  }, [initialLocale])
+
+  const value = React.useMemo<I18nContextValue>(
+    () => ({
+      locale,
+      translations,
+      t,
+      setLocale,
+    }),
+    [locale, translations, t, setLocale]
+  )
+
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>
+}
+
+/**
+ * Hook to access i18n context
+ *
+ * @example
+ * function MyComponent() {
+ *   const { t, locale, setLocale } = useI18n()
+ *
+ *   return (
+ *     <div>
+ *       <p>{t('ui.select.placeholder')}</p>
+ *       <p>{t('ui.pagination.showing', { from: 1, to: 10, total: 100 })}</p>
+ *       <button onClick={() => setLocale('ru')}>Switch to Russian</button>
+ *     </div>
+ *   )
+ * }
+ */
+export function useI18n(): I18nContextValue {
+  const context = React.useContext(I18nContext)
+
+  if (!context) {
+    // Return default implementation if no provider
+    // This allows components to work without provider (using English defaults)
+    return {
+      locale: 'en',
+      translations: defaultTranslations,
+      t: (key: string, params?: Record<string, string | number>) => {
+        const value = getNestedValue(
+          defaultTranslations as unknown as Record<string, unknown>,
+          key
+        )
+        if (value === undefined) return key
+        return interpolate(value, params)
+      },
+      setLocale: () => {
+        if (typeof window !== 'undefined' && window.location.hostname === 'localhost') {
+          console.warn(
+            '[i18n] setLocale called but no I18nProvider found. Wrap your app with I18nProvider to enable locale switching.'
+          )
+        }
+      },
+    }
+  }
+
+  return context
+}
+
+/**
+ * Hook to get the translation function only
+ * Useful when you only need translations without other context values
+ *
+ * @example
+ * function MyComponent() {
+ *   const t = useTranslation()
+ *   return <span>{t('ui.form.save')}</span>
+ * }
+ */
+export function useTranslation() {
+  const { t } = useI18n()
+  return t
+}
+
+/**
+ * Hook to get current locale
+ *
+ * @example
+ * function MyComponent() {
+ *   const locale = useLocale()
+ *   return <span>Current: {locale}</span>
+ * }
+ */
+export function useLocale(): LocaleCode {
+  const { locale } = useI18n()
+  return locale
+}
+
+/**
+ * Alias for useTranslation
+ * Lightweight hook that just returns the t function
+ * Works with or without I18nProvider (falls back to English)
+ *
+ * @example
+ * function MyComponent() {
+ *   const t = useT()
+ *   return <span>{t('ui.form.save')}</span>
+ * }
+ */
+export const useT = useTranslation
+
+/**
+ * Type-safe translation hook
+ *
+ * Returns a translation function that only accepts valid keys from your translations type.
+ * Use this when you want compile-time checking of translation keys.
+ *
+ * @example
+ * ```typescript
+ * 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
+ *   return <span>{t('ui.form.typo')}</span> // Compile error!
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With merged translations (app + extensions)
+ * import type { AppTranslations } from '@/i18n/types'
+ *
+ * function MyComponent() {
+ *   const t = useTypedT<AppTranslations>()
+ *   return <span>{t('leads.form.title')}</span> // OK if leads is in AppTranslations
+ * }
+ * ```
+ */
+export function useTypedT<T extends object>(): (
+  key: import('./utils/path-keys').PathKeys<T>,
+  params?: Record<string, string | number>
+) => string {
+  const { t } = useI18n()
+  return t as (
+    key: import('./utils/path-keys').PathKeys<T>,
+    params?: Record<string, string | number>
+  ) => string
+}
+
+/**
+ * Get translation without hook (for class components or non-React contexts)
+ * Always uses English defaults, no context support
+ *
+ * @example
+ * // In a class component
+ * render() {
+ *   const title = getT('layouts.errors.somethingWentWrong')
+ *   return <h1>{title}</h1>
+ * }
+ *
+ * @example
+ * // With interpolation
+ * const message = getT('ui.pagination.showing', { from: 1, to: 10, total: 100 })
+ */
+export function getT(
+  key: string,
+  params?: Record<string, string | number>
+): string {
+  const value = getNestedValue(
+    defaultTranslations as unknown as Record<string, unknown>,
+    key
+  )
+  if (value === undefined) return key
+  return interpolate(value, params)
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// Context & Hooks
+export { I18nProvider, useI18n, useTranslation, useLocale, useT, useTypedT, getT } from './context'
+
+// Types
+export type {
+  I18nTranslations,
+  PartialTranslations,
+  LocaleCode,
+  I18nContextValue,
+  I18nProviderProps,
+  DeepPartial,
+  I18nKeys,
+  I18nTranslationFn,
+} from './types'
+
+// Type-safe keys utilities
+export type {
+  PathKeys,
+  TranslationFn,
+  TypedTranslationFn,
+  TranslationKeys,
+} from './utils/path-keys'
+
+// Locales
+export { en, ru, ko } from './locales'
+
+// Utils
+export { interpolate, mergeTranslations, createTranslations } from './utils'