@djangocfg/nextjs 2.1.110 → 2.1.112

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 ?? 'as-needed';
+
+  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';

package/src/sitemap/generator.ts

@@ -2,32 +2,107 @@
  * Sitemap Generator
  *
  * Generates XML sitemap from configuration
+ * Supports i18n with hreflang tags for multilingual sites
  */
 
 import type { SitemapUrl } from '../types';
+import type { SitemapI18nOptions } from './types';
+
+export interface GenerateSitemapXmlOptions {
+  urls: SitemapUrl[];
+  i18n?: SitemapI18nOptions;
+  siteUrl: string;
+}
 
 /**
  * Generate XML sitemap string from URLs
+ * Supports i18n with hreflang alternate links
  */
-export function generateSitemapXml(urls: SitemapUrl[]): string {
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+export function generateSitemapXml(
+  urlsOrOptions: SitemapUrl[] | GenerateSitemapXmlOptions
+): string {
+  // Support both old signature (just urls) and new signature (options object)
+  const isOptionsObject = !Array.isArray(urlsOrOptions);
+  const urls = isOptionsObject ? urlsOrOptions.urls : urlsOrOptions;
+  const i18n = isOptionsObject ? urlsOrOptions.i18n : undefined;
+  const siteUrl = isOptionsObject ? urlsOrOptions.siteUrl : '';
+
+  // Add xhtml namespace if i18n is enabled
+  const namespaces = i18n
+    ? `xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+        xmlns:xhtml="http://www.w3.org/1999/xhtml"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9
+        http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"`
+    : `xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9
-        http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">
+        http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd"`;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset ${namespaces}>
 ${urls
-  .map(
-    ({ loc, lastmod, changefreq, priority }) => `  <url>
-    <loc>${escapeXml(loc)}</loc>
+  .map(({ loc, lastmod, changefreq, priority }) => {
+    const hreflangLinks = i18n
+      ? generateHreflangLinks(loc, i18n, siteUrl)
+      : '';
+
+    return `  <url>
+    <loc>${escapeXml(loc)}</loc>${hreflangLinks}
     ${lastmod ? `<lastmod>${formatDate(lastmod)}</lastmod>` : ''}
     ${changefreq ? `<changefreq>${changefreq}</changefreq>` : ''}
     ${priority !== undefined ? `<priority>${priority.toFixed(1)}</priority>` : ''}
-  </url>`
-  )
+  </url>`;
+  })
   .join('\n')}
 </urlset>`;
 }
 
+/**
+ * Generate hreflang links for a URL
+ */
+function generateHreflangLinks(
+  loc: string,
+  i18n: SitemapI18nOptions,
+  siteUrl: string
+): string {
+  const { locales, defaultLocale } = i18n;
+
+  // Extract the path without locale prefix from the URL
+  // e.g., https://example.com/en/page -> /page
+  const baseSiteUrl = siteUrl.endsWith('/') ? siteUrl.slice(0, -1) : siteUrl;
+  let path = loc.replace(baseSiteUrl, '');
+
+  // Remove locale prefix if present
+  for (const locale of locales) {
+    const localePrefix = `/${locale}`;
+    if (path === localePrefix || path.startsWith(`${localePrefix}/`)) {
+      path = path.slice(localePrefix.length) || '/';
+      break;
+    }
+  }
+
+  const links: string[] = [];
+
+  // Add hreflang for each locale
+  for (const locale of locales) {
+    const localePath = path === '/' ? `/${locale}` : `/${locale}${path}`;
+    const fullUrl = `${baseSiteUrl}${localePath}`;
+    links.push(
+      `    <xhtml:link rel="alternate" hreflang="${locale}" href="${escapeXml(fullUrl)}"/>`
+    );
+  }
+
+  // Add x-default pointing to default locale
+  const defaultPath = path === '/' ? `/${defaultLocale}` : `/${defaultLocale}${path}`;
+  const defaultUrl = `${baseSiteUrl}${defaultPath}`;
+  links.push(
+    `    <xhtml:link rel="alternate" hreflang="x-default" href="${escapeXml(defaultUrl)}"/>`
+  );
+
+  return '\n' + links.join('\n');
+}
+
 /**
  * Format date for sitemap (ISO 8601)
  */