@djangocfg/nextjs 2.1.109 → 2.1.111

package/src/i18n/provider.tsx

@@ -0,0 +1,91 @@
+/**
+ * i18n Provider for Next.js App Router
+ *
+ * Bridges next-intl with @djangocfg/i18n
+ * Provides translations to both Server and Client components
+ *
+ * @example
+ * ```tsx
+ * // app/[locale]/layout.tsx
+ * import { I18nProvider } from '@djangocfg/nextjs/i18n';
+ * import { getMessages, getLocale } from '@djangocfg/nextjs/i18n/server';
+ *
+ * export default async function LocaleLayout({ children, params }) {
+ *   const locale = await getLocale(params);
+ *   const messages = await getMessages();
+ *
+ *   return (
+ *     <I18nProvider locale={locale} messages={messages}>
+ *       {children}
+ *     </I18nProvider>
+ *   );
+ * }
+ * ```
+ */
+
+'use client';
+
+import { NextIntlClientProvider } from 'next-intl';
+import { I18nProvider as DjangoCfgI18nProvider } from '@djangocfg/i18n';
+import type { I18nProviderProps, LocaleCode } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider Component
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Unified i18n Provider
+ *
+ * Wraps both NextIntlClientProvider and @djangocfg/i18n's I18nProvider
+ * This ensures both next-intl hooks and @djangocfg/i18n hooks work correctly
+ */
+export function I18nProvider({
+  locale,
+  messages,
+  timeZone = 'UTC',
+  now,
+  children,
+}: I18nProviderProps) {
+  return (
+    <NextIntlClientProvider
+      locale={locale}
+      messages={messages}
+      timeZone={timeZone}
+      now={now}
+    >
+      <DjangoCfgI18nProvider
+        locale={locale as LocaleCode}
+        translations={messages}
+      >
+        {children}
+      </DjangoCfgI18nProvider>
+    </NextIntlClientProvider>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Lightweight Provider (next-intl only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Next-intl only provider (without @djangocfg/i18n context)
+ * Use if you only need next-intl hooks
+ */
+export function NextIntlProvider({
+  locale,
+  messages,
+  timeZone = 'UTC',
+  now,
+  children,
+}: I18nProviderProps) {
+  return (
+    <NextIntlClientProvider
+      locale={locale}
+      messages={messages}
+      timeZone={timeZone}
+      now={now}
+    >
+      {children}
+    </NextIntlClientProvider>
+  );
+}

package/src/i18n/proxy.ts

@@ -0,0 +1,81 @@
+/**
+ * i18n Proxy for Next.js App Router (Next.js 16+)
+ *
+ * Handles locale detection and routing
+ *
+ * @example
+ * ```ts
+ * // proxy.ts
+ * export { proxy as default, config } from '@djangocfg/nextjs/i18n';
+ *
+ * // Or with custom routing:
+ * import { createProxy } from '@djangocfg/nextjs/i18n';
+ * import { routing } from './i18n/routing';
+ *
+ * export default createProxy(routing);
+ * export const config = { matcher: [...] };
+ * ```
+ */
+
+import createIntlMiddleware from 'next-intl/middleware';
+import type { NextRequest } from 'next/server';
+
+import { routing, createRouting } from './routing';
+import type { I18nConfig } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Proxy Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create i18n proxy handler with custom routing configuration
+ */
+export function createProxy(routingConfig?: ReturnType<typeof createRouting>) {
+  const config = routingConfig ?? routing;
+  return createIntlMiddleware(config);
+}
+
+/**
+ * Create i18n proxy from config options
+ */
+export function createProxyFromConfig(config: Partial<I18nConfig>) {
+  const routingConfig = createRouting(config);
+  return createIntlMiddleware(routingConfig);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Proxy
+// ─────────────────────────────────────────────────────────────────────────────
+
+const handleI18nRouting = createProxy();
+
+/**
+ * Default proxy function using default routing
+ *
+ * @example
+ * ```ts
+ * // proxy.ts
+ * export { proxy as default, config } from '@djangocfg/nextjs/i18n';
+ * ```
+ */
+export function proxy(request: NextRequest) {
+  return handleI18nRouting(request);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Default proxy config
+ * Matches all paths except static files, API routes, and Next.js internals
+ *
+ * @example
+ * ```ts
+ * // proxy.ts
+ * export { proxy as default, config } from '@djangocfg/nextjs/i18n';
+ * ```
+ */
+export const config = {
+  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)',],
+};

package/src/i18n/request.ts

@@ -0,0 +1,141 @@
+/**
+ * i18n Request Configuration for Server Components
+ *
+ * Provides translations to server components via next-intl's request scope
+ *
+ * @example
+ * ```ts
+ * // i18n/request.ts in your app
+ * import { createRequestConfig } from '@djangocfg/nextjs/i18n';
+ * import { en, ru, ko } from '@djangocfg/i18n';
+ * import { leadsI18n } from '@djangocfg/ext-leads';
+ *
+ * export default createRequestConfig({
+ *   locales: { en, ru, ko },
+ *   extensions: [leadsI18n],
+ * });
+ * ```
+ */
+
+import { getRequestConfig } from 'next-intl/server';
+import { mergeTranslations, en, ru, ko } from '@djangocfg/i18n';
+import type { I18nTranslations, LocaleCode } from '@djangocfg/i18n';
+import type { Messages } from './types';
+import { routing } from './routing';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RequestConfigOptions {
+  /** Base locale translations from @djangocfg/i18n */
+  locales?: Record<LocaleCode, I18nTranslations>;
+  /** Extension i18n instances to merge */
+  extensions?: Array<{
+    namespace: string;
+    locales: Record<string, Record<string, unknown>>;
+  }>;
+  /** Custom message loader (overrides locales) */
+  loadMessages?: (locale: LocaleCode) => Promise<Messages> | Messages;
+  /** Time zone for date/time formatting */
+  timeZone?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Locales
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_LOCALES: Record<LocaleCode, I18nTranslations> = {
+  en,
+  ru,
+  ko,
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Message Loading
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Load and merge messages for a locale
+ */
+function loadMessages(
+  locale: LocaleCode,
+  options: RequestConfigOptions
+): Messages {
+  // Get base translations
+  const locales = options.locales ?? DEFAULT_LOCALES;
+  const baseMessages = locales[locale] ?? locales.en ?? en;
+
+  // If no extensions, return base
+  if (!options.extensions?.length) {
+    return baseMessages as Messages;
+  }
+
+  // Merge extension translations
+  let mergedMessages = { ...baseMessages } as Messages;
+
+  for (const extension of options.extensions) {
+    const extMessages = extension.locales[locale] ?? extension.locales.en;
+    if (extMessages) {
+      mergedMessages = mergeTranslations(mergedMessages, {
+        [extension.namespace]: extMessages,
+      }) as Messages;
+    }
+  }
+
+  return mergedMessages;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Request Config Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create request configuration for next-intl
+ *
+ * This is used in your app's `i18n/request.ts` file
+ *
+ * @example
+ * ```ts
+ * // i18n/request.ts
+ * import { createRequestConfig } from '@djangocfg/nextjs/i18n';
+ * import { leadsI18n } from '@djangocfg/ext-leads';
+ * import { paymentsI18n } from '@djangocfg/ext-payments';
+ *
+ * export default createRequestConfig({
+ *   extensions: [leadsI18n, paymentsI18n],
+ * });
+ * ```
+ */
+export function createRequestConfig(options: RequestConfigOptions = {}) {
+  return getRequestConfig(async ({ requestLocale }) => {
+    // Get locale from request or default
+    let locale = await requestLocale;
+
+    // Validate and fallback to default
+    if (!locale || !routing.locales.includes(locale as LocaleCode)) {
+      locale = routing.defaultLocale;
+    }
+
+    // Load messages
+    const messages = options.loadMessages
+      ? await options.loadMessages(locale as LocaleCode)
+      : loadMessages(locale as LocaleCode, options);
+
+    return {
+      locale,
+      messages,
+      timeZone: options.timeZone ?? 'UTC',
+    };
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Export
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Default request config with base @djangocfg/i18n translations
+ * Can be used directly if no extensions are needed
+ */
+export default createRequestConfig();

package/src/i18n/routing.ts

@@ -0,0 +1,84 @@
+/**
+ * i18n Routing Configuration
+ *
+ * Creates routing configuration for next-intl
+ * Used by proxy and navigation components
+ */
+
+import { defineRouting } from 'next-intl/routing';
+import type { I18nConfig, LocaleCode } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Configuration
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_LOCALES: LocaleCode[] = ['en', 'ru', 'ko'];
+const DEFAULT_LOCALE: LocaleCode = 'en';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Routing Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create routing configuration for next-intl
+ *
+ * @example
+ * ```ts
+ * // i18n/routing.ts
+ * import { createRouting } from '@djangocfg/nextjs/i18n';
+ *
+ * export const routing = createRouting({
+ *   locales: ['en', 'ru', 'ko'],
+ *   defaultLocale: 'en',
+ * });
+ * ```
+ */
+export function createRouting(config?: Partial<I18nConfig>) {
+  const locales = config?.locales ?? DEFAULT_LOCALES;
+  const defaultLocale = config?.defaultLocale ?? DEFAULT_LOCALE;
+  const localePrefix = config?.localePrefix ?? 'always';
+
+  return defineRouting({
+    locales,
+    defaultLocale,
+    localePrefix,
+  });
+}
+
+/**
+ * Default routing configuration
+ * Can be overridden by app-specific configuration
+ */
+export const routing = createRouting();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Locale Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if a locale is supported
+ */
+export function isValidLocale(
+  locale: string,
+  supportedLocales: readonly string[] = DEFAULT_LOCALES
+): locale is LocaleCode {
+  return supportedLocales.includes(locale as LocaleCode);
+}
+
+/**
+ * Get locale from params (handles async params in Next.js 15+)
+ */
+export async function getLocaleFromParams(
+  params: Promise<{ locale: string }> | { locale: string }
+): Promise<LocaleCode> {
+  const resolved = await params;
+  return resolved.locale as LocaleCode;
+}
+
+/**
+ * Generate static params for all locales
+ * Use in generateStaticParams for locale pages
+ */
+export function generateLocaleParams(locales: readonly string[] = DEFAULT_LOCALES) {
+  return locales.map((locale) => ({ locale }));
+}

package/src/i18n/server.ts

@@ -0,0 +1,175 @@
+/**
+ * Server-side i18n Utilities
+ *
+ * For use in Server Components, Server Actions, and Route Handlers
+ *
+ * @example
+ * ```tsx
+ * // In a Server Component
+ * import { getTranslations, getLocale } from '@djangocfg/nextjs/i18n/server';
+ *
+ * export default async function Page() {
+ *   const t = await getTranslations('HomePage');
+ *   const locale = await getLocale();
+ *
+ *   return <h1>{t('title')}</h1>;
+ * }
+ * ```
+ */
+
+import {
+  getTranslations as getNextIntlTranslations,
+  getLocale as getNextIntlLocale,
+  getMessages as getNextIntlMessages,
+  getNow,
+  getTimeZone,
+  getFormatter,
+} from 'next-intl/server';
+import type { LocaleCode, Messages, LocaleParams } from './types';
+import { isValidLocale, generateLocaleParams } from './routing';
+
+// Re-export routing utilities for convenience
+export { isValidLocale, generateLocaleParams };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core Server Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get translations for Server Components
+ *
+ * @example
+ * ```tsx
+ * const t = await getTranslations('HomePage');
+ * return <h1>{t('title')}</h1>;
+ *
+ * // Or without namespace
+ * const t = await getTranslations();
+ * return <h1>{t('HomePage.title')}</h1>;
+ * ```
+ */
+export async function getTranslations<Namespace extends string = never>(
+  namespace?: Namespace
+) {
+  return getNextIntlTranslations(namespace);
+}
+
+/**
+ * Get current locale in Server Components
+ */
+export async function getLocale(): Promise<LocaleCode> {
+  return (await getNextIntlLocale()) as LocaleCode;
+}
+
+/**
+ * Get all messages for the current request
+ * Useful for passing to I18nProvider in layouts
+ */
+export async function getMessages(): Promise<Messages> {
+  return (await getNextIntlMessages()) as Messages;
+}
+
+/**
+ * Get current time for the request
+ * Useful for consistent time-based formatting
+ */
+export { getNow };
+
+/**
+ * Get timezone for the request
+ */
+export { getTimeZone };
+
+/**
+ * Get formatter for dates, numbers, etc.
+ */
+export { getFormatter };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Locale Extraction Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extract locale from page/layout params
+ *
+ * @example
+ * ```tsx
+ * // app/[locale]/page.tsx
+ * export default async function Page({ params }) {
+ *   const locale = await getLocaleFromParams(params);
+ *   // ...
+ * }
+ * ```
+ */
+export async function getLocaleFromParams(
+  params: Promise<LocaleParams> | LocaleParams
+): Promise<LocaleCode> {
+  const resolved = await params;
+  return resolved.locale as LocaleCode;
+}
+
+/**
+ * Shorthand for getting locale from params
+ * Alias for getLocaleFromParams
+ */
+export const extractLocale = getLocaleFromParams;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Typed Translation Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get typed translations for a specific namespace
+ *
+ * @example
+ * ```tsx
+ * const t = await getNamespacedTranslations('payments');
+ * return <span>{t('balance.available')}</span>;
+ * ```
+ */
+export async function getNamespacedTranslations(namespace: string) {
+  return getNextIntlTranslations(namespace);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Metadata Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Generate localized metadata for pages
+ *
+ * @example
+ * ```tsx
+ * // app/[locale]/about/page.tsx
+ * import { generateLocalizedMetadata } from '@djangocfg/nextjs/i18n/server';
+ *
+ * export async function generateMetadata({ params }) {
+ *   return generateLocalizedMetadata(params, {
+ *     titleKey: 'AboutPage.meta.title',
+ *     descriptionKey: 'AboutPage.meta.description',
+ *   });
+ * }
+ * ```
+ */
+export async function generateLocalizedMetadata(
+  params: Promise<LocaleParams> | LocaleParams,
+  options: {
+    titleKey?: string;
+    descriptionKey?: string;
+    namespace?: string;
+  } = {}
+) {
+  const locale = await getLocaleFromParams(params);
+  const t = await getTranslations(options.namespace);
+
+  return {
+    title: options.titleKey ? t(options.titleKey as never) : undefined,
+    description: options.descriptionKey ? t(options.descriptionKey as never) : undefined,
+    // Add locale to alternate languages
+    alternates: {
+      languages: {
+        [locale]: `/${locale}`,
+      },
+    },
+  };
+}

package/src/i18n/types.ts

@@ -0,0 +1,88 @@
+/**
+ * i18n Types for Next.js App Router
+ *
+ * Integrates next-intl with @djangocfg/i18n
+ */
+
+import type { LocaleCode, I18nTranslations } from '@djangocfg/i18n';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Configuration Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface I18nConfig {
+  /** Supported locales */
+  locales: LocaleCode[];
+  /** Default locale (fallback) */
+  defaultLocale: LocaleCode;
+  /** Locale prefix strategy */
+  localePrefix?: 'always' | 'as-needed' | 'never';
+  /** Cookie name for locale preference */
+  cookieName?: string;
+  /** Paths to exclude from locale routing (e.g., '/api', '/_next') */
+  excludedPaths?: string[];
+}
+
+export interface I18nPluginOptions extends I18nConfig {
+  /** Path to i18n request config file (default: './src/i18n/request.ts' or './i18n/request.ts') */
+  requestConfig?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Translation Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Messages structure - compatible with next-intl */
+export type Messages = I18nTranslations & {
+  [namespace: string]: Record<string, unknown>;
+};
+
+/** Locale-specific messages loader */
+export type MessagesLoader = (locale: LocaleCode) => Promise<Messages> | Messages;
+
+/** Extension translations that can be merged */
+export interface ExtensionMessages {
+  namespace: string;
+  messages: Record<LocaleCode, Record<string, unknown>>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface I18nProviderProps {
+  /** Current locale */
+  locale: LocaleCode;
+  /** Translation messages */
+  messages: Messages;
+  /** Time zone for date/time formatting */
+  timeZone?: string;
+  /** Now value for relative time */
+  now?: Date;
+  /** Children */
+  children: React.ReactNode;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Routing Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface LocaleParams {
+  locale: string;
+}
+
+export interface LocaleLayoutProps {
+  children: React.ReactNode;
+  params: Promise<LocaleParams>;
+}
+
+export interface LocalePageProps {
+  params: Promise<LocaleParams>;
+  searchParams?: Promise<Record<string, string | string[] | undefined>>;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Re-exports from @djangocfg/i18n
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type { LocaleCode, I18nTranslations } from '@djangocfg/i18n';