@djangocfg/i18n 2.1.111

package/src/utils/merge.ts

@@ -0,0 +1,88 @@
+import type { I18nTranslations, PartialTranslations } from '../types'
+
+type AnyObject = { [key: string]: unknown }
+
+/**
+ * Deep merge two objects
+ */
+function deepMerge(target: AnyObject, source: AnyObject): AnyObject {
+  const result = { ...target }
+
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key]
+      const targetValue = result[key]
+
+      if (
+        sourceValue !== null &&
+        typeof sourceValue === 'object' &&
+        !Array.isArray(sourceValue) &&
+        targetValue !== null &&
+        typeof targetValue === 'object' &&
+        !Array.isArray(targetValue)
+      ) {
+        // Recursively merge objects
+        result[key] = deepMerge(
+          targetValue as AnyObject,
+          sourceValue as AnyObject
+        )
+      } else if (sourceValue !== undefined) {
+        // Override with source value
+        result[key] = sourceValue
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Merge base translations with partial overrides or additional namespaces
+ *
+ * @example
+ * // Override existing keys
+ * const customRu = mergeTranslations(ru, {
+ *   ui: {
+ *     select: {
+ *       placeholder: 'Выберите марку авто...'
+ *     }
+ *   }
+ * })
+ *
+ * @example
+ * // Add app-specific namespace
+ * const appTranslations = mergeTranslations(en, {
+ *   hub: {
+ *     nav: { home: 'Home' }
+ *   }
+ * })
+ */
+export function mergeTranslations<T extends Record<string, unknown> = Record<string, unknown>>(
+  base: I18nTranslations,
+  overrides: PartialTranslations | T
+): I18nTranslations & T {
+  return deepMerge(
+    base as unknown as AnyObject,
+    overrides as unknown as AnyObject
+  ) as unknown as I18nTranslations & T
+}
+
+/**
+ * Create translations from multiple partial sources
+ *
+ * @example
+ * const translations = createTranslations(
+ *   en,           // base
+ *   uiOverrides,  // UI customizations
+ *   appStrings    // App-specific strings
+ * )
+ */
+export function createTranslations(
+  base: I18nTranslations,
+  ...overrides: PartialTranslations[]
+): I18nTranslations {
+  return overrides.reduce<I18nTranslations>(
+    (acc, override) => mergeTranslations(acc, override),
+    base
+  )
+}

package/src/utils/path-keys.ts

@@ -0,0 +1,85 @@
+/**
+ * Type-safe translation keys
+ *
+ * Generates a union of all possible dot-notation paths from a nested object type.
+ *
+ * @example
+ * ```typescript
+ * type Translations = {
+ *   ui: {
+ *     form: { save: string; cancel: string }
+ *     select: { placeholder: string }
+ *   }
+ * }
+ *
+ * type Keys = PathKeys<Translations>
+ * // = "ui.form.save" | "ui.form.cancel" | "ui.select.placeholder"
+ * ```
+ */
+
+/**
+ * Recursively generates dot-notation paths for nested object types
+ *
+ * - For leaf values (string), returns the accumulated path
+ * - For nested objects, recursively builds paths
+ * - Limits depth to prevent infinite recursion with circular types
+ */
+export type PathKeys<T, Prefix extends string = '', Depth extends number[] = []> =
+  // Limit recursion depth to 10 levels (prevents infinite types)
+  Depth['length'] extends 10
+    ? never
+    : T extends string
+      ? Prefix
+      : T extends object
+        ? {
+            [K in keyof T & string]: PathKeys<
+              T[K],
+              Prefix extends '' ? K : `${Prefix}.${K}`,
+              [...Depth, 0]
+            >
+          }[keyof T & string]
+        : never
+
+/**
+ * Type-safe translation function signature
+ *
+ * @example
+ * ```typescript
+ * import type { TranslationFn, I18nTranslations } from '@djangocfg/i18n'
+ *
+ * // Type-safe t function
+ * const t: TranslationFn<I18nTranslations> = useT()
+ * t('ui.form.save') // OK
+ * t('ui.form.typo') // Error: Argument of type '"ui.form.typo"' is not assignable
+ * ```
+ */
+export type TranslationFn<T extends object> = {
+  (key: PathKeys<T>, params?: Record<string, string | number>): string
+}
+
+/**
+ * Creates a type-safe translation function type for a specific translations object
+ *
+ * @example
+ * ```typescript
+ * // In extension
+ * import type { TypedTranslationFn } from '@djangocfg/i18n'
+ * import type { LeadsTranslations } from './types'
+ *
+ * type LeadsT = TypedTranslationFn<{ leads: LeadsTranslations }>
+ * ```
+ */
+export type TypedTranslationFn<T extends object> = TranslationFn<T>
+
+/**
+ * Extracts the keys type from a translations object
+ *
+ * @example
+ * ```typescript
+ * import type { TranslationKeys, I18nTranslations } from '@djangocfg/i18n'
+ *
+ * type Keys = TranslationKeys<I18nTranslations>
+ * // = "ui.form.save" | "ui.select.placeholder" | ...
+ * ```
+ */
+export type TranslationKeys<T extends object> = PathKeys<T>