@djangocfg/i18n 2.1.190 → 2.1.192

package/README.md

@@ -181,16 +181,86 @@ function MyComponent() {
 }
 ```
 
+## Type-safe next-intl Integration
+
+Override `useTranslations` in your app's `global.d.ts` to get compile-time key validation.
+
+### 1. Merge translations (flat, no namespace)
+
+```ts
+// i18n/request.ts
+import { en as baseEn } from '@djangocfg/i18n/locales';
+import { en as appEn } from './locales';
+
+const locales = {
+  en: { ...baseEn, ...appEn },
+};
+```
+
+### 2. Add `global.d.ts` to your app root
+
+```ts
+// 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>;
+}
+```
+
+### 3. Include in tsconfig.json
+
+```json
+{ "include": ["global.d.ts", "app/**/*.ts", ...] }
+```
+
+Now invalid keys and namespaces produce compile errors:
+
+```ts
+const t = useTranslations('machines');
+t('title');              // OK
+t('dialogs.delete.title'); // OK
+t('NONEXISTENT');        // Error!
+
+useTranslations('BOGUS'); // Error!
+```
+
+> **Why not `use-intl` AppConfig?** The standard `declare module 'use-intl' { interface AppConfig }` augmentation doesn't propagate through pnpm's nested `node_modules`. Overriding `useTranslations` in `next-intl` directly works reliably.
+
+### Exported utility types
+
+| Type | Description |
+|------|-------------|
+| `NestedKeyOf<T>` | All dot-separated paths (leaves + namespaces) |
+| `NestedValueOf<T, P>` | Resolve value type by dot path |
+| `NamespaceKeys<T, A>` | Paths resolving to objects (valid namespaces) |
+| `MessageKeys<T, A>` | Paths resolving to strings (valid keys) |
+| `IntlTranslator<M, NS>` | Type-safe translator with `t()`, `rich()`, `has()`, `raw()` |
+
 ## Extending Translations
 
-### mergeTranslations()
+### Spread merge (recommended for next-intl apps)
+
+```ts
+import { en as baseEn } from '@djangocfg/i18n/locales';
+const messages = { ...baseEn, ...appEn };
+```
+
+### mergeTranslations() (deep merge with overrides)
 
 ```tsx
 import { mergeTranslations, ru } from '@djangocfg/i18n'
 
 const customRu = mergeTranslations(ru, {
   ui: { select: { placeholder: 'Выберите...' } },
-  app: { title: 'Мое приложение' }
 })
 ```
 

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import * as react from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
@@ -72,6 +73,27 @@ type TypedTranslationFn<T extends object> = TranslationFn<T>;
  * ```
  */
 type TranslationKeys<T extends object> = PathKeys<T>;
+/** All dot-separated paths (both leaves and namespaces) */
+type NestedKeyOf<T> = T extends object ? {
+    [K in keyof T & string]: K | `${K}.${NestedKeyOf<T[K]>}`;
+}[keyof T & string] : never;
+/** Resolve nested value by dot-separated path */
+type NestedValueOf<T, P extends string> = P extends `${infer K}.${infer R}` ? K extends keyof T ? NestedValueOf<T[K], R> : never : P extends keyof T ? T[P] : never;
+/** Paths that resolve to objects (valid useTranslations namespaces) */
+type NamespaceKeys<T, A extends string> = {
+    [K in A]: NestedValueOf<T, K> extends string ? never : K;
+}[A];
+/** Paths that resolve to strings (valid t() keys) */
+type MessageKeys<T, A extends string> = {
+    [K in A]: NestedValueOf<T, K> extends string ? K : never;
+}[A];
+/** Type-safe translator returned by useTranslations(namespace) */
+type IntlTranslator<Messages, NS extends NamespaceKeys<Messages, NestedKeyOf<Messages>>> = {
+    <K extends MessageKeys<NestedValueOf<Messages, NS>, NestedKeyOf<NestedValueOf<Messages, NS>>>>(key: K, values?: Record<string, unknown>): string;
+    rich<K extends MessageKeys<NestedValueOf<Messages, NS>, NestedKeyOf<NestedValueOf<Messages, NS>>>>(key: K, values?: Record<string, unknown>): react.ReactNode;
+    has(key: NestedKeyOf<NestedValueOf<Messages, NS>>): boolean;
+    raw(key: NestedKeyOf<NestedValueOf<Messages, NS>>): unknown;
+};
 
 /**
  * All valid translation keys for base I18nTranslations
@@ -1019,4 +1041,4 @@ declare function mergeTranslations<T extends Record<string, unknown> = Record<st
  */
 declare function createTranslations(base: I18nTranslations, ...overrides: PartialTranslations[]): I18nTranslations;
 
-export { type DeepPartial, type I18nContextValue, type I18nKeys, I18nProvider, type I18nProviderProps, type I18nTranslationFn, type I18nTranslations, type LocaleCode, type PartialTranslations, type PathKeys, type TranslationFn, type TranslationKeys, type TypedTranslationFn, createTranslations, en, getT, interpolate, ko, mergeTranslations, ru, useI18n, useLocale, useT, useTranslation, useTypedT };
+export { type DeepPartial, type I18nContextValue, type I18nKeys, I18nProvider, type I18nProviderProps, type I18nTranslationFn, type I18nTranslations, type IntlTranslator, type LocaleCode, type MessageKeys, type NamespaceKeys, type NestedKeyOf, type NestedValueOf, type PartialTranslations, type PathKeys, type TranslationFn, type TranslationKeys, type TypedTranslationFn, createTranslations, en, getT, interpolate, ko, mergeTranslations, ru, useI18n, useLocale, useT, useTranslation, useTypedT };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/i18n",
-  "version": "2.1.190",
+  "version": "2.1.192",
   "description": "Lightweight i18n library for @djangocfg packages with built-in translations for English, Russian, and Korean",
   "keywords": [
     "i18n",
@@ -72,13 +72,13 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@djangocfg/llm": "^2.1.190",
+    "@djangocfg/llm": "^2.1.192",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
     "jiti": "^2.4.2"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.190",
+    "@djangocfg/typescript-config": "^2.1.192",
     "@types/node": "^25.2.3",
     "@types/react": "^19.1.0",
     "eslint": "^9.37.0",

package/src/index.ts

@@ -19,6 +19,11 @@ export type {
   TranslationFn,
   TypedTranslationFn,
   TranslationKeys,
+  NestedKeyOf,
+  NestedValueOf,
+  NamespaceKeys,
+  MessageKeys,
+  IntlTranslator,
 } from './utils/path-keys'
 
 // Locales

package/src/utils/index.ts

@@ -1,4 +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'
+export type { PathKeys, TranslationFn, TypedTranslationFn, TranslationKeys, NestedKeyOf, NestedValueOf, NamespaceKeys, MessageKeys, IntlTranslator } from './path-keys'

package/src/utils/path-keys.ts

@@ -83,3 +83,42 @@ export type TypedTranslationFn<T extends object> = TranslationFn<T>
  * ```
  */
 export type TranslationKeys<T extends object> = PathKeys<T>
+
+// --- next-intl augmentation utilities ---
+// Used in app global.d.ts to override useTranslations with type-safe keys.
+// The standard use-intl AppConfig augmentation doesn't propagate through
+// pnpm's nested node_modules, so apps override useTranslations directly.
+
+/** All dot-separated paths (both leaves and namespaces) */
+export type NestedKeyOf<T> = T extends object
+  ? { [K in keyof T & string]: K | `${K}.${NestedKeyOf<T[K]>}` }[keyof T & string]
+  : never
+
+/** Resolve nested value by dot-separated path */
+export type NestedValueOf<T, P extends string> = P extends `${infer K}.${infer R}`
+  ? K extends keyof T ? NestedValueOf<T[K], R> : never
+  : P extends keyof T ? T[P] : never
+
+/** Paths that resolve to objects (valid useTranslations namespaces) */
+export type NamespaceKeys<T, A extends string> = {
+  [K in A]: NestedValueOf<T, K> extends string ? never : K
+}[A]
+
+/** Paths that resolve to strings (valid t() keys) */
+export type MessageKeys<T, A extends string> = {
+  [K in A]: NestedValueOf<T, K> extends string ? K : never
+}[A]
+
+/** Type-safe translator returned by useTranslations(namespace) */
+export type IntlTranslator<Messages, NS extends NamespaceKeys<Messages, NestedKeyOf<Messages>>> = {
+  <K extends MessageKeys<NestedValueOf<Messages, NS>, NestedKeyOf<NestedValueOf<Messages, NS>>>>(
+    key: K,
+    values?: Record<string, unknown>,
+  ): string
+  rich<K extends MessageKeys<NestedValueOf<Messages, NS>, NestedKeyOf<NestedValueOf<Messages, NS>>>>(
+    key: K,
+    values?: Record<string, unknown>,
+  ): import('react').ReactNode
+  has(key: NestedKeyOf<NestedValueOf<Messages, NS>>): boolean
+  raw(key: NestedKeyOf<NestedValueOf<Messages, NS>>): unknown
+}