@djangocfg/i18n 2.1.111

package/src/types.ts

@@ -0,0 +1,656 @@
+import type { PathKeys, TranslationFn } from './utils/path-keys'
+
+/**
+ * All valid translation keys for base I18nTranslations
+ *
+ * @example
+ * ```typescript
+ * import type { I18nKeys } from '@djangocfg/i18n'
+ *
+ * const key: I18nKeys = 'ui.form.save' // OK
+ * const bad: I18nKeys = 'ui.form.typo' // Error
+ * ```
+ */
+export type I18nKeys = PathKeys<I18nTranslations>
+
+/**
+ * Type-safe translation function for base translations
+ */
+export type I18nTranslationFn = TranslationFn<I18nTranslations>
+
+/**
+ * Core translation structure for @djangocfg packages
+ *
+ * This type defines all translatable strings used across the component library.
+ * Each package section contains its own namespace to avoid conflicts.
+ */
+export interface I18nTranslations {
+  /**
+   * UI Components (ui-core, ui-nextjs)
+   */
+  ui: {
+    /** Select/Combobox/MultiSelect components */
+    select: {
+      placeholder: string
+      search: string
+      noResults: string
+      selectAll: string
+      clearAll: string
+      /** Template: "+{count} more" */
+      moreItems: string
+      loading: string
+    }
+
+    /** Pagination components */
+    pagination: {
+      previous: string
+      next: string
+      first: string
+      last: string
+      /** Template: "Page {page}" */
+      page: string
+      /** Template: "of {total}" */
+      of: string
+      /** Template: "{from}-{to} of {total}" */
+      showing: string
+    }
+
+    /** Dialog/Modal components */
+    dialog: {
+      close: string
+      confirm: string
+      cancel: string
+    }
+
+    /** Form components and validation */
+    form: {
+      submit: string
+      cancel: string
+      save: string
+      delete: string
+      edit: string
+      create: string
+      update: string
+      reset: string
+      clear: string
+      loading: string
+      saving: string
+      deleting: string
+      required: string
+      optional: string
+      /** Template: "{min} characters minimum" */
+      minLength: string
+      /** Template: "{max} characters maximum" */
+      maxLength: string
+      invalidEmail: string
+      invalidUrl: string
+      invalidPhone: string
+      passwordMismatch: string
+    }
+
+    /** Date/Time components */
+    datetime: {
+      today: string
+      yesterday: string
+      tomorrow: string
+      now: string
+      /** Template: "{count} seconds ago" */
+      secondsAgo: string
+      /** Template: "{count} minutes ago" */
+      minutesAgo: string
+      /** Template: "{count} hours ago" */
+      hoursAgo: string
+      /** Template: "{count} days ago" */
+      daysAgo: string
+      pickDate: string
+      pickTime: string
+      pickDateTime: string
+      pickDateRange: string
+    }
+
+    /** File upload components */
+    file: {
+      upload: string
+      uploading: string
+      dragDrop: string
+      browse: string
+      remove: string
+      /** Template: "Max size: {size}" */
+      maxSize: string
+      invalidType: string
+      tooLarge: string
+    }
+
+    /** Table components */
+    table: {
+      noData: string
+      loading: string
+      /** Template: "Showing {from}-{to} of {total}" */
+      showing: string
+      rowsPerPage: string
+      sortAsc: string
+      sortDesc: string
+      filter: string
+      clearFilters: string
+      selectAll: string
+      deselectAll: string
+      /** Template: "{count} selected" */
+      selected: string
+    }
+
+    /** Common actions */
+    actions: {
+      view: string
+      copy: string
+      copied: string
+      copyToClipboard: string
+      download: string
+      share: string
+      refresh: string
+      retry: string
+      expand: string
+      collapse: string
+      showMore: string
+      showLess: string
+      seeAll: string
+      goBack: string
+      remove: string
+      previousSlide: string
+      nextSlide: string
+    }
+
+    /** Phone input */
+    phone: {
+      searchCountries: string
+      noCountries: string
+    }
+
+    /** Navigation (for tabs, mobile sheets, etc.) */
+    navigation: {
+      /** Title for navigation sheet/modal */
+      title: string
+    }
+
+    /** Common states */
+    states: {
+      loading: string
+      empty: string
+      error: string
+      success: string
+      warning: string
+      info: string
+      pending: string
+      active: string
+      inactive: string
+      enabled: string
+      disabled: string
+    }
+
+    /** Error messages */
+    errors: {
+      generic: string
+      network: string
+      timeout: string
+      notFound: string
+      unauthorized: string
+      forbidden: string
+      serverError: string
+      validation: string
+      unknown: string
+    }
+  }
+
+  /**
+   * Layout components (@djangocfg/layouts)
+   */
+  layouts: {
+    /** Sidebar component */
+    sidebar: {
+      toggle: string
+      collapse: string
+      expand: string
+    }
+
+    /** Navigation */
+    navigation: {
+      menu: string
+      home: string
+      back: string
+      forward: string
+      toggleMobile: string
+      breadcrumb: string
+    }
+
+    /** Profile/User section */
+    profile: {
+      settings: string
+      account: string
+      logout: string
+      login: string
+      signUp: string
+      signOut: string
+      userMenu: string
+    }
+
+    /** Theme */
+    theme: {
+      toggle: string
+      light: string
+      dark: string
+      system: string
+    }
+
+    /** Search */
+    search: {
+      placeholder: string
+      noResults: string
+      recentSearches: string
+      clearHistory: string
+    }
+
+    /** Mobile drawer */
+    mobile: {
+      closeMenu: string
+    }
+
+    /** Error pages */
+    errors: {
+      somethingWentWrong: string
+      tryRefreshing: string
+      refreshPage: string
+      goBack: string
+      goHome: string
+      needHelp: string
+      contactSupport: string
+      /** Template: "If the problem persists, please contact {email}" */
+      persistsContact: string
+      /** Error titles */
+      error: string
+      badRequest: string
+      authRequired: string
+      accessDenied: string
+      pageNotFound: string
+      requestTimeout: string
+      serverError: string
+      badGateway: string
+      serviceUnavailable: string
+      gatewayTimeout: string
+      /** Error descriptions */
+      badRequestDesc: string
+      authRequiredDesc: string
+      accessDeniedDesc: string
+      pageNotFoundDesc: string
+      requestTimeoutDesc: string
+      serverErrorDesc: string
+      badGatewayDesc: string
+      serviceUnavailableDesc: string
+      gatewayTimeoutDesc: string
+      unknownErrorDesc: string
+    }
+
+    /** Push notifications */
+    push: {
+      enableNotifications: string
+      stayUpdated: string
+      enable: string
+      notNow: string
+      dismiss: string
+    }
+
+    /** Auth dialog */
+    auth: {
+      authRequired: string
+      pleaseSignIn: string
+      goToSignIn: string
+    }
+
+    /** MCP Chat */
+    chat: {
+      aiAssistant: string
+      defaultTitle: string
+      newChat: string
+      closeChat: string
+      switchToFloating: string
+      switchToSidebar: string
+      dragToResize: string
+      howCanIHelp: string
+    }
+
+    /** PWA Install */
+    pwa: {
+      /** A2HS Hint */
+      addToHomeScreen: string
+      installApp: string
+      tapToLearnHow: string
+      clickToSeeGuide: string
+      tapToInstall: string
+      installing: string
+      dismiss: string
+      appLogo: string
+      /** iOS Guide */
+      iosTitle: string
+      iosDescription: string
+      iosStep1Title: string
+      iosStep1Desc: string
+      iosStep2Title: string
+      iosStep2Desc: string
+      iosStep3Title: string
+      iosStep3Desc: string
+      gotIt: string
+      /** Desktop Guide */
+      desktopTitle: string
+      desktopDescription: string
+      desktopDescSafari: string
+      desktopTip: string
+      desktopFirefoxNote: string
+      /** Desktop steps - Chromium */
+      chromiumStep1Title: string
+      chromiumStep1Desc: string
+      chromiumStep2Title: string
+      chromiumStep2Desc: string
+      chromiumStep3Title: string
+      chromiumStep3Desc: string
+      /** Desktop steps - Firefox */
+      firefoxStep1Title: string
+      firefoxStep1Desc: string
+      firefoxStep2Title: string
+      firefoxStep2Desc: string
+      firefoxStep3Title: string
+      firefoxStep3Desc: string
+      /** Desktop steps - Safari */
+      safariStep1Title: string
+      safariStep1Desc: string
+      safariStep2Title: string
+      safariStep2Desc: string
+      /** Desktop steps - Unknown */
+      unknownStep1Title: string
+      unknownStep1Desc: string
+      unknownStep2Title: string
+      unknownStep2Desc: string
+      unknownStep3Title: string
+      unknownStep3Desc: string
+      close: string
+    }
+
+    /** Profile page */
+    profilePage: {
+      /** Page title */
+      title: string
+      /** Sections */
+      account: string
+      personalInfo: string
+      work: string
+      security: string
+      actions: string
+      /** Fields */
+      email: string
+      firstName: string
+      lastName: string
+      company: string
+      position: string
+      phone: string
+      /** Values */
+      notSet: string
+      on: string
+      off: string
+      /** Actions */
+      save: string
+      saving: string
+      cancel: string
+      signOut: string
+      deleteAccount: string
+      deleting: string
+      /** 2FA */
+      twoFactorAuth: string
+      /** Avatar */
+      avatar: string
+      changeAvatar: string
+      /** Membership */
+      memberSince: string
+      /** Placeholders */
+      enterField: string
+      /** Messages */
+      profileUpdated: string
+      avatarUpdated: string
+      failedToUpdate: string
+      failedToUploadAvatar: string
+      selectImageFile: string
+      fileTooLarge: string
+      /** Not authenticated */
+      notAuthenticated: string
+      pleaseLogIn: string
+      /** Delete account dialog */
+      deleteAccountTitle: string
+      deleteAccountDesc: string
+      typeToConfirm: string
+      confirmationWord: string
+    }
+  }
+
+  /**
+   * API/Network related messages (@djangocfg/api)
+   */
+  api: {
+    errors: {
+      networkError: string
+      connectionFailed: string
+      requestTimeout: string
+      serverUnavailable: string
+      invalidResponse: string
+      rateLimited: string
+    }
+    status: {
+      connecting: string
+      connected: string
+      disconnected: string
+      reconnecting: string
+    }
+    /** Logout dialog */
+    logout: {
+      title: string
+      message: string
+      confirm: string
+      cancel: string
+    }
+  }
+
+  /**
+   * Centrifugo WebSocket (@djangocfg/centrifugo)
+   */
+  centrifugo: {
+    /** Monitor component */
+    monitor: {
+      title: string
+      description: string
+      openMonitor: string
+      openDebugPanel: string
+      widgetTitle: string
+    }
+    /** Tabs */
+    tabs: {
+      connection: string
+      messages: string
+      subscriptions: string
+    }
+    /** Subscriptions list */
+    subscriptionsList: {
+      title: string
+      notConnected: string
+      noActiveSubscriptions: string
+    }
+    /** Status */
+    status: {
+      connected: string
+      disconnected: string
+      connecting: string
+      connect: string
+      uptime: string
+      subscriptions: string
+      realtimeUnavailable: string
+    }
+    /** Messages feed */
+    feed: {
+      title: string
+      noMessages: string
+      pausedClickToResume: string
+      autoScrollOn: string
+      autoScrollOff: string
+      viewData: string
+    }
+    /** Filters */
+    filters: {
+      title: string
+      active: string
+      clear: string
+      searchMessages: string
+      level: string
+      type: string
+      source: string
+      autoScrollToLatest: string
+    }
+    /** Debug panel */
+    debug: {
+      title: string
+      description: string
+      openDebugPanel: string
+      tabConnection: string
+      tabLogs: string
+      tabSubscriptions: string
+    }
+  }
+
+  /**
+   * Heavy tools (@djangocfg/ui-tools)
+   */
+  tools: {
+    /** Code viewer/editor */
+    code: {
+      copyCode: string
+      noContent: string
+    }
+
+    /** Diagram/Mermaid */
+    diagram: {
+      title: string
+      clickToView: string
+    }
+
+    /** Image viewer */
+    image: {
+      noImage: string
+      failedToLoad: string
+      zoomIn: string
+      zoomOut: string
+      fitToView: string
+      flipHorizontal: string
+      flipVertical: string
+      rotate: string
+      fullscreen: string
+    }
+
+    /** Gallery/Lightbox */
+    gallery: {
+      noImages: string
+      lightbox: string
+      previous: string
+      next: string
+      close: string
+      download: string
+      share: string
+    }
+
+    /** Video player */
+    video: {
+      play: string
+      fullscreen: string
+      unavailable: string
+    }
+
+    /** Audio player */
+    audio: {
+      restart: string
+      back: string
+      forward: string
+      volume: string
+    }
+
+    /** Color picker */
+    color: {
+      pick: string
+    }
+
+    /** OpenAPI viewer */
+    openapi: {
+      response: string
+      noResponse: string
+      required: string
+      optional: string
+      searchEndpoints: string
+      all: string
+      methods: string
+      path: string
+      description: string
+      navigation: string
+      previous: string
+      next: string
+      bearerToken: string
+    }
+
+    /** JSON form */
+    form: {
+      title: string
+    }
+  }
+}
+
+/**
+ * Deeply partial type for translation overrides
+ */
+export type PartialTranslations = DeepPartial<I18nTranslations>
+
+/**
+ * Helper type for deep partial
+ */
+export type DeepPartial<T> = T extends object
+  ? { [P in keyof T]?: DeepPartial<T[P]> }
+  : T
+
+/**
+ * Supported locale codes
+ */
+export type LocaleCode = 'en' | 'ru' | 'ko' | string
+
+/**
+ * I18n context value
+ */
+export interface I18nContextValue {
+  /** Current locale code */
+  locale: LocaleCode
+  /** Current translations */
+  translations: I18nTranslations
+  /**
+   * Get translated string by key path
+   * @param key - Dot-notation key path (e.g., "ui.select.placeholder")
+   * @param params - Optional interpolation parameters
+   */
+  t: (key: string, params?: Record<string, string | number>) => string
+  /**
+   * Change current locale
+   */
+  setLocale: (locale: LocaleCode) => void
+}
+
+/**
+ * I18n provider props
+ */
+export interface I18nProviderProps {
+  children: React.ReactNode
+  /** Initial locale */
+  locale?: LocaleCode
+  /** Translations for the current locale */
+  translations?: I18nTranslations | PartialTranslations
+  /** All available translations by locale */
+  allTranslations?: Record<LocaleCode, I18nTranslations | PartialTranslations>
+  /** Callback when locale changes */
+  onLocaleChange?: (locale: LocaleCode) => void
+}

package/src/utils/get-value.ts

@@ -0,0 +1,30 @@
+/**
+ * Get a nested value from an object using dot notation
+ *
+ * @example
+ * getNestedValue({ ui: { select: { placeholder: 'Select...' } } }, 'ui.select.placeholder')
+ * // => 'Select...'
+ */
+export function getNestedValue(
+  obj: Record<string, unknown>,
+  path: string
+): string | undefined {
+  const keys = path.split('.')
+  let current: unknown = obj
+
+  for (const key of keys) {
+    if (current === null || current === undefined) {
+      return undefined
+    }
+    if (typeof current !== 'object') {
+      return undefined
+    }
+    current = (current as Record<string, unknown>)[key]
+  }
+
+  if (typeof current === 'string') {
+    return current
+  }
+
+  return undefined
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export { interpolate } from './interpolate'
+export { mergeTranslations, createTranslations } from './merge'
+export { getNestedValue } from './get-value'
+export type { PathKeys, TranslationFn, TypedTranslationFn, TranslationKeys } from './path-keys'

package/src/utils/interpolate.ts

@@ -0,0 +1,23 @@
+/**
+ * Interpolate variables in a translation string
+ *
+ * @example
+ * interpolate("Hello, {name}!", { name: "World" })
+ * // => "Hello, World!"
+ *
+ * interpolate("+{count} more", { count: 5 })
+ * // => "+5 more"
+ */
+export function interpolate(
+  template: string,
+  params?: Record<string, string | number>
+): string {
+  if (!params) return template
+
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    if (key in params) {
+      return String(params[key])
+    }
+    return match
+  })
+}