@djangocfg/nextjs 2.1.110 → 2.1.112

package/src/i18n/client.ts

@@ -0,0 +1,221 @@
+/**
+ * Client-side i18n Hooks
+ *
+ * For use in Client Components ('use client')
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { useTranslations, useLocale } from '@djangocfg/nextjs/i18n/client';
+ *
+ * export function MyComponent() {
+ *   const t = useTranslations('HomePage');
+ *   const locale = useLocale();
+ *
+ *   return <h1>{t('title')}</h1>;
+ * }
+ * ```
+ */
+
+'use client';
+
+import {
+  useTranslations as useNextIntlTranslations,
+  useLocale as useNextIntlLocale,
+  useMessages,
+  useNow,
+  useTimeZone,
+  useFormatter,
+} from 'next-intl';
+import { useRouter, usePathname } from './navigation';
+import { routing } from './routing';
+import type { LocaleCode } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core Client Hooks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get translations in Client Components
+ *
+ * @example
+ * ```tsx
+ * const t = useTranslations('HomePage');
+ * return <h1>{t('title')}</h1>;
+ *
+ * // With interpolation
+ * return <p>{t('greeting', { name: 'John' })}</p>;
+ * ```
+ */
+export function useTranslations<Namespace extends string = never>(
+  namespace?: Namespace
+) {
+  return useNextIntlTranslations(namespace);
+}
+
+/**
+ * Get current locale in Client Components
+ */
+export function useLocale(): LocaleCode {
+  return useNextIntlLocale() as LocaleCode;
+}
+
+/**
+ * Get all messages
+ * Useful for passing to child providers
+ */
+export { useMessages };
+
+/**
+ * Get current time
+ */
+export { useNow };
+
+/**
+ * Get timezone
+ */
+export { useTimeZone };
+
+/**
+ * Get formatter for dates, numbers, etc.
+ */
+export { useFormatter };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Convenience Hooks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Shorthand for useTranslations
+ * Alias for compatibility with @djangocfg/i18n
+ */
+export const useT = useTranslations;
+
+/**
+ * Get namespaced translations
+ *
+ * @example
+ * ```tsx
+ * const pt = useNamespacedTranslations('payments');
+ * return <span>{pt('balance.available')}</span>;
+ * ```
+ */
+export function useNamespacedTranslations(namespace: string) {
+  return useNextIntlTranslations(namespace);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Formatting Hooks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Format a date according to locale
+ *
+ * @example
+ * ```tsx
+ * const formatDate = useDateFormatter();
+ * return <span>{formatDate(new Date())}</span>;
+ * ```
+ */
+export function useDateFormatter() {
+  const formatter = useFormatter();
+  return (date: Date | number, options?: Parameters<typeof formatter.dateTime>[1]) =>
+    formatter.dateTime(date, options);
+}
+
+/**
+ * Format a number according to locale
+ *
+ * @example
+ * ```tsx
+ * const formatNumber = useNumberFormatter();
+ * return <span>{formatNumber(1234.56)}</span>;
+ * ```
+ */
+export function useNumberFormatter() {
+  const formatter = useFormatter();
+  return (number: number, options?: Parameters<typeof formatter.number>[1]) =>
+    formatter.number(number, options);
+}
+
+/**
+ * Format relative time
+ *
+ * @example
+ * ```tsx
+ * const formatRelative = useRelativeTimeFormatter();
+ * return <span>{formatRelative(new Date())}</span>;
+ * ```
+ */
+export function useRelativeTimeFormatter() {
+  const formatter = useFormatter();
+  return (date: Date | number, options?: Parameters<typeof formatter.relativeTime>[1]) =>
+    formatter.relativeTime(date, options);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Locale Switching Hooks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get list of available locales from routing config
+ *
+ * @example
+ * ```tsx
+ * const locales = useLocales();
+ * // ['en', 'ru', 'ko']
+ * ```
+ */
+export function useLocales(): LocaleCode[] {
+  return routing.locales as LocaleCode[];
+}
+
+/**
+ * Get default locale from routing config
+ */
+export function useDefaultLocale(): LocaleCode {
+  return routing.defaultLocale as LocaleCode;
+}
+
+/**
+ * Hook to change current locale
+ *
+ * @example
+ * ```tsx
+ * const changeLocale = useChangeLocale();
+ *
+ * <button onClick={() => changeLocale('ru')}>
+ *   Switch to Russian
+ * </button>
+ * ```
+ */
+export function useChangeLocale() {
+  const router = useRouter();
+  const pathname = usePathname();
+
+  return (locale: LocaleCode) => {
+    router.replace(pathname, { locale });
+  };
+}
+
+/**
+ * Combined hook for locale switching
+ * Returns current locale, available locales, and change function
+ *
+ * @example
+ * ```tsx
+ * const { locale, locales, changeLocale } = useLocaleSwitcher();
+ *
+ * <select value={locale} onChange={(e) => changeLocale(e.target.value)}>
+ *   {locales.map(l => <option key={l} value={l}>{l}</option>)}
+ * </select>
+ * ```
+ */
+export function useLocaleSwitcher() {
+  const locale = useLocale();
+  const locales = useLocales();
+  const changeLocale = useChangeLocale();
+
+  return { locale, locales, changeLocale };
+}

package/src/i18n/components/LocaleSwitcher.tsx

@@ -0,0 +1,60 @@
+/**
+ * LocaleSwitcher Component (Smart)
+ *
+ * Wrapper around @djangocfg/layouts LocaleSwitcher with next-intl hooks.
+ * Automatically gets locale data from routing config.
+ *
+ * @example
+ * ```tsx
+ * import { LocaleSwitcher } from '@djangocfg/nextjs/i18n/components';
+ *
+ * // Basic usage (uses all locales from routing config)
+ * <LocaleSwitcher />
+ *
+ * // With custom locales
+ * <LocaleSwitcher locales={['en', 'ru']} />
+ *
+ * // With custom labels
+ * <LocaleSwitcher
+ *   labels={{
+ *     en: 'English',
+ *     ru: 'Русский',
+ *     ko: '한국어',
+ *   }}
+ * />
+ * ```
+ */
+
+'use client';
+
+import {
+  LocaleSwitcher as BaseLocaleSwitcher,
+  type LocaleSwitcherProps as BaseLocaleSwitcherProps,
+} from '@djangocfg/layouts';
+
+import { useLocaleSwitcher } from '../client';
+import type { LocaleCode } from '../types';
+
+export interface LocaleSwitcherProps
+  extends Omit<BaseLocaleSwitcherProps, 'locale' | 'locales' | 'onChange'> {
+  /** Available locales (defaults to all from routing config) */
+  locales?: LocaleCode[];
+}
+
+export function LocaleSwitcher({
+  locales: customLocales,
+  ...props
+}: LocaleSwitcherProps) {
+  const { locale, locales: routingLocales, changeLocale } = useLocaleSwitcher();
+
+  const availableLocales = customLocales || routingLocales;
+
+  return (
+    <BaseLocaleSwitcher
+      locale={locale}
+      locales={availableLocales}
+      onChange={changeLocale}
+      {...props}
+    />
+  );
+}

package/src/i18n/components/index.ts

@@ -0,0 +1,7 @@
+/**
+ * i18n Components
+ *
+ * Ready-to-use UI components for internationalization
+ */
+
+export { LocaleSwitcher, type LocaleSwitcherProps } from './LocaleSwitcher';

package/src/i18n/index.ts

@@ -0,0 +1,149 @@
+/**
+ * i18n Module for Next.js App Router
+ *
+ * Complete internationalization solution integrating next-intl with @djangocfg/i18n
+ *
+ * @example Setup
+ * ```ts
+ * // 1. Create i18n/routing.ts
+ * import { createRouting } from '@djangocfg/nextjs/i18n';
+ *
+ * export const routing = createRouting({
+ *   locales: ['en', 'ru', 'ko'],
+ *   defaultLocale: 'en',
+ * });
+ *
+ * // 2. Create i18n/request.ts
+ * import { createRequestConfig } from '@djangocfg/nextjs/i18n';
+ * import { leadsI18n } from '@djangocfg/ext-leads';
+ *
+ * export default createRequestConfig({
+ *   extensions: [leadsI18n],
+ * });
+ *
+ * // 3. Create i18n/navigation.ts
+ * import { createNavigation } from '@djangocfg/nextjs/i18n';
+ * import { routing } from './routing';
+ *
+ * export const { Link, redirect, usePathname, useRouter } = createNavigation(routing);
+ *
+ * // 4. Create proxy.ts
+ * import { createProxy } from '@djangocfg/nextjs/i18n';
+ * import { routing } from './i18n/routing';
+ *
+ * export default createProxy(routing);
+ * export const config = { matcher: ['/((?!api|_next|.*\\..*).*)'] };
+ *
+ * // 5. Update next.config.ts
+ * import { createBaseNextConfig } from '@djangocfg/nextjs/config';
+ *
+ * export default createBaseNextConfig({
+ *   i18n: {
+ *     locales: ['en', 'ru', 'ko'],
+ *     defaultLocale: 'en',
+ *   },
+ * });
+ *
+ * // 6. Create app/[locale]/layout.tsx
+ * import { I18nProvider } from '@djangocfg/nextjs/i18n';
+ * import { getMessages, getLocaleFromParams } from '@djangocfg/nextjs/i18n/server';
+ *
+ * export default async function LocaleLayout({ children, params }) {
+ *   const locale = await getLocaleFromParams(params);
+ *   const messages = await getMessages();
+ *
+ *   return (
+ *     <html lang={locale}>
+ *       <body>
+ *         <I18nProvider locale={locale} messages={messages}>
+ *           {children}
+ *         </I18nProvider>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type {
+  I18nConfig,
+  I18nPluginOptions,
+  I18nProviderProps,
+  Messages,
+  MessagesLoader,
+  ExtensionMessages,
+  LocaleParams,
+  LocaleLayoutProps,
+  LocalePageProps,
+  LocaleCode,
+  I18nTranslations,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Routing
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  createRouting,
+  routing,
+  isValidLocale,
+  getLocaleFromParams,
+  generateLocaleParams,
+} from './routing';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Navigation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  createNavigation,
+  createNavigationFromConfig,
+  Link,
+  redirect,
+  usePathname,
+  useRouter,
+  getPathname,
+} from './navigation';
+
+export type { LinkProps } from './navigation';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { I18nProvider, NextIntlProvider } from './provider';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Request Config (for i18n/request.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  createRequestConfig,
+  type RequestConfigOptions,
+} from './request';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Proxy (Next.js 16+)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  createProxy,
+  createProxyFromConfig,
+  proxy,
+  config as proxyConfig,
+} from './proxy';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Plugin (for next.config.ts) - import from '@djangocfg/nextjs/i18n/plugin'
+// Not exported here to avoid SWC plugin issues with Turbopack
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Components
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { LocaleSwitcher, type LocaleSwitcherProps } from './components';

package/src/i18n/navigation.ts

@@ -0,0 +1,90 @@
+/**
+ * i18n Navigation Utilities
+ *
+ * Provides locale-aware navigation components and functions
+ *
+ * @example
+ * ```ts
+ * // In your app's i18n/navigation.ts
+ * import { createNavigation } from '@djangocfg/nextjs/i18n';
+ * import { routing } from './routing';
+ *
+ * export const { Link, redirect, usePathname, useRouter } = createNavigation(routing);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using in components
+ * import { Link, usePathname } from '@/i18n/navigation';
+ *
+ * function Nav() {
+ *   const pathname = usePathname();
+ *   return <Link href="/about">About</Link>;
+ * }
+ * ```
+ */
+
+import { createNavigation as createNextIntlNavigation } from 'next-intl/navigation';
+import { routing, createRouting } from './routing';
+import type { I18nConfig } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Navigation Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create navigation utilities with custom routing
+ *
+ * Returns locale-aware versions of:
+ * - Link: Locale-prefixed links
+ * - redirect: Server-side redirect with locale
+ * - usePathname: Current pathname without locale prefix
+ * - useRouter: Router with locale-aware navigation
+ * - getPathname: Get pathname for a route
+ */
+export function createNavigation(routingConfig?: ReturnType<typeof createRouting>) {
+  const config = routingConfig ?? routing;
+  return createNextIntlNavigation(config);
+}
+
+/**
+ * Create navigation from config options
+ */
+export function createNavigationFromConfig(config: Partial<I18nConfig>) {
+  const routingConfig = createRouting(config);
+  return createNextIntlNavigation(routingConfig);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Navigation (using default routing)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Default navigation utilities
+ * Use these directly or create custom ones with createNavigation()
+ */
+export const {
+  Link,
+  redirect,
+  usePathname,
+  useRouter,
+  getPathname,
+} = createNavigation();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Props for locale-aware Link component
+ */
+export interface LinkProps {
+  /** Target href */
+  href: string;
+  /** Target locale (optional, defaults to current) */
+  locale?: string;
+  /** Children */
+  children?: React.ReactNode;
+  /** Additional props passed to Next.js Link */
+  [key: string]: unknown;
+}

package/src/i18n/plugin.ts

@@ -0,0 +1,66 @@
+/**
+ * i18n Plugin for Next.js Configuration
+ *
+ * Wraps next-intl plugin for use with createBaseNextConfig
+ *
+ * @example
+ * ```ts
+ * // next.config.ts
+ * import { createBaseNextConfig } from '@djangocfg/nextjs/config';
+ *
+ * export default createBaseNextConfig({
+ *   i18n: {
+ *     locales: ['en', 'ru', 'ko'],
+ *     defaultLocale: 'en',
+ *   },
+ * });
+ * ```
+ */
+
+import createNextIntlPlugin from 'next-intl/plugin';
+import type { NextConfig } from 'next';
+import type { I18nPluginOptions } from './types';
+
+export type { I18nPluginOptions } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Plugin Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create next-intl plugin wrapper
+ *
+ * @param options - i18n configuration options
+ * @returns Next.js config wrapper function
+ */
+export function createI18nPlugin(options?: I18nPluginOptions) {
+  // Determine request config path
+  const requestConfigPath = options?.requestConfig
+    ?? './i18n/request.ts';
+
+  // Create next-intl plugin
+  const withNextIntl = createNextIntlPlugin(requestConfigPath);
+
+  return withNextIntl;
+}
+
+/**
+ * Apply i18n plugin to Next.js config
+ *
+ * @param config - Base Next.js config
+ * @param options - i18n options
+ * @returns Modified Next.js config
+ */
+export function withI18n(
+  config: NextConfig,
+  options?: I18nPluginOptions
+): NextConfig {
+  const plugin = createI18nPlugin(options);
+  return plugin(config);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Export for direct use
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { createNextIntlPlugin };

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>
+  );
+}