@flightdev/i18n 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+/**
+ * @flightdev/i18n - Agnostic Internationalization
+ *
+ * @example
+ * ```typescript
+ * import { createI18n } from '@flightdev/i18n';
+ * import { i18next } from '@flightdev/i18n/i18next';
+ *
+ * const i18n = createI18n(i18next({
+ *   locales: ['en', 'es', 'fr'],
+ *   defaultLocale: 'en',
+ * }));
+ *
+ * const t = i18n.t;
+ * t('hello'); // "Hello"
+ * ```
+ */
+type Locale = string;
+interface TranslationOptions {
+    count?: number;
+    context?: string;
+    defaultValue?: string;
+    [key: string]: unknown;
+}
+interface I18nAdapter {
+    readonly name: string;
+    readonly locale: Locale;
+    readonly locales: Locale[];
+    init(): Promise<void>;
+    setLocale(locale: Locale): Promise<void>;
+    t(key: string, options?: TranslationOptions): string;
+    exists(key: string): boolean;
+    loadNamespace(namespace: string): Promise<void>;
+}
+type I18nAdapterFactory<TConfig = unknown> = (config: TConfig) => I18nAdapter;
+interface I18nServiceOptions {
+    defaultLocale?: Locale;
+    fallbackLocale?: Locale;
+}
+interface I18nService {
+    readonly adapter: I18nAdapter;
+    readonly locale: Locale;
+    readonly locales: Locale[];
+    init(): Promise<void>;
+    setLocale(locale: Locale): Promise<void>;
+    t(key: string, options?: TranslationOptions): string;
+    exists(key: string): boolean;
+}
+declare function createI18n(adapter: I18nAdapter, _options?: I18nServiceOptions): I18nService;
+declare function getLocaleFromRequest(request: Request, supportedLocales: Locale[], defaultLocale: Locale): Locale;
+declare function formatNumber(value: number, locale: Locale, options?: Intl.NumberFormatOptions): string;
+declare function formatDate(date: Date, locale: Locale, options?: Intl.DateTimeFormatOptions): string;
+declare function formatRelativeTime(date: Date, locale: Locale): string;
+/**
+ * Type-safe i18n service with autocompletion for translation keys.
+ *
+ * Use with generated types from `@flightdev/i18n/typegen` for
+ * full TypeScript-level validation of translation keys.
+ *
+ * @typeParam TKey - Union type of valid translation keys
+ *
+ * @example
+ * ```typescript
+ * import type { TranslationKey } from './i18n.d.ts';
+ * import { createTypedI18n } from '@flightdev/i18n';
+ *
+ * const i18n = createTypedI18n<TranslationKey>(adapter);
+ *
+ * i18n.t('nav.home');        // Valid - autocomplete suggests keys
+ * i18n.t('nonexistent');     // TypeScript error
+ * ```
+ */
+interface TypedI18nService<TKey extends string> {
+    /** The underlying adapter instance */
+    readonly adapter: I18nAdapter;
+    /** Current active locale */
+    readonly locale: Locale;
+    /** All supported locales */
+    readonly locales: Locale[];
+    /** Initialize the i18n service */
+    init(): Promise<void>;
+    /** Change the current locale */
+    setLocale(locale: Locale): Promise<void>;
+    /**
+     * Translate a key to the current locale.
+     * TypeScript will validate that key is a valid TranslationKey.
+     *
+     * @param key - Translation key (type-checked)
+     * @param options - Interpolation values and options
+     * @returns Translated string
+     */
+    t(key: TKey, options?: TranslationOptions): string;
+    /**
+     * Check if a translation key exists.
+     *
+     * @param key - Translation key to check
+     * @returns true if key exists in current locale
+     */
+    exists(key: TKey): boolean;
+    /**
+     * Load a namespace dynamically (if supported by adapter).
+     *
+     * @param namespace - Namespace to load
+     */
+    loadNamespace(namespace: string): Promise<void>;
+}
+/**
+ * Creates a type-safe i18n service with autocompletion for translation keys.
+ *
+ * This is the recommended way to use i18n in TypeScript projects.
+ * Generate types using `@flightdev/i18n/typegen` and pass
+ * the `TranslationKey` type to get full IDE support.
+ *
+ * @typeParam TKey - Union type of valid translation keys
+ * @param adapter - i18n adapter instance
+ * @param options - Service options
+ * @returns Type-safe i18n service
+ *
+ * @example
+ * ```typescript
+ * // 1. Generate types (one-time or in build)
+ * // npx flight i18n:typegen --input ./locales/en --output ./src/i18n.d.ts
+ *
+ * // 2. Import generated types
+ * import type { TranslationKey } from './i18n.d.ts';
+ * import { createTypedI18n } from '@flightdev/i18n';
+ * import { formatjs } from '@flightdev/i18n/formatjs';
+ *
+ * // 3. Create type-safe service
+ * const i18n = createTypedI18n<TranslationKey>(formatjs({ ... }));
+ *
+ * // 4. Enjoy type safety!
+ * i18n.t('common.buttons.submit');  // Autocomplete works
+ * i18n.t('typo.here');              // TypeScript error
+ * ```
+ */
+declare function createTypedI18n<TKey extends string>(adapter: I18nAdapter, _options?: I18nServiceOptions): TypedI18nService<TKey>;
+/**
+ * Helper type to extract parameters from a translation string.
+ * Matches {{param}} and {param} patterns.
+ *
+ * @example
+ * ```typescript
+ * type Params = ExtractParams<'Hello, {{name}}! You have {{count}} messages.'>;
+ * // { name: unknown; count: unknown }
+ * ```
+ */
+type ExtractParams<T extends string> = T extends `${string}{{${infer Param}}}${infer Rest}` ? {
+    [K in Param]: unknown;
+} & ExtractParams<Rest> : T extends `${string}{${infer Param}}${infer Rest}` ? {
+    [K in Param]: unknown;
+} & ExtractParams<Rest> : Record<string, never>;
+/**
+ * Namespace separator for translation keys (e.g., 'common:button.submit')
+ */
+type NamespacedKey<NS extends string, Key extends string> = `${NS}:${Key}`;
+/**
+ * Split a namespaced key into namespace and key parts
+ */
+declare function parseNamespacedKey(key: string): {
+    namespace: string | null;
+    key: string;
+};
+
+export { type ExtractParams, type I18nAdapter, type I18nAdapterFactory, type I18nService, type I18nServiceOptions, type Locale, type NamespacedKey, type TranslationOptions, type TypedI18nService, createI18n, createTypedI18n, formatDate, formatNumber, formatRelativeTime, getLocaleFromRequest, parseNamespacedKey };

package/dist/index.js

@@ -0,0 +1,18 @@
+import {
+  createI18n,
+  createTypedI18n,
+  formatDate,
+  formatNumber,
+  formatRelativeTime,
+  getLocaleFromRequest,
+  parseNamespacedKey
+} from "./chunk-F5CV7JNA.js";
+export {
+  createI18n,
+  createTypedI18n,
+  formatDate,
+  formatNumber,
+  formatRelativeTime,
+  getLocaleFromRequest,
+  parseNamespacedKey
+};

package/dist/middleware.d.ts

@@ -0,0 +1,107 @@
+import { I18nRoutingConfig } from './routing.js';
+export { I18nRoutingStrategy } from './routing.js';
+import { Locale } from './index.js';
+
+/**
+ * i18n Middleware Factory for Flight Framework
+ *
+ * Creates file-based middleware for automatic locale detection and routing.
+ * Designed to integrate seamlessly with Flight's `_middleware.ts` convention.
+ *
+ * @example
+ * ```typescript
+ * // src/routes/_middleware.ts
+ * import { createI18nMiddleware } from '@flightdev/i18n/middleware';
+ *
+ * export const middleware = createI18nMiddleware({
+ *   locales: ['en', 'es', 'fr'],
+ *   defaultLocale: 'en',
+ *   routing: 'prefix',
+ *   prefixDefault: false, // /about for 'en', /es/about for 'es'
+ * });
+ * ```
+ *
+ * @module @flightdev/i18n/middleware
+ */
+
+/**
+ * Options for creating i18n middleware
+ */
+interface I18nMiddlewareOptions extends I18nRoutingConfig {
+    /**
+     * Whether to redirect to localized URL if no locale is detected
+     * Only applies to 'prefix' strategy
+     * @default true
+     */
+    redirectOnMissingLocale?: boolean;
+    /**
+     * Custom locale detection function
+     * If provided, this runs first before other detection strategies
+     * Return null to fall back to standard detection
+     */
+    detectLocale?: (request: Request) => Locale | null | Promise<Locale | null>;
+    /**
+     * Callback when locale is resolved
+     * Useful for analytics or custom logging
+     */
+    onLocaleResolved?: (locale: Locale, request: Request) => void | Promise<void>;
+}
+/**
+ * Middleware function signature for Flight
+ */
+type I18nMiddleware = (request: Request) => Promise<Response | null>;
+/**
+ * Creates an i18n middleware for Flight's file-based routing.
+ *
+ * The middleware handles:
+ * 1. Locale detection from URL, domain, cookie, or Accept-Language header
+ * 2. Automatic redirects to localized URLs (prefix strategy)
+ * 3. Setting locale cookies for persistence
+ *
+ * @param options - Middleware configuration
+ * @returns Middleware function for use in `_middleware.ts`
+ *
+ * @example
+ * ```typescript
+ * // Simple prefix strategy
+ * export const middleware = createI18nMiddleware({
+ *   locales: ['en', 'es', 'fr'],
+ *   defaultLocale: 'en',
+ *   routing: 'prefix',
+ * });
+ *
+ * // Domain-based routing
+ * export const middleware = createI18nMiddleware({
+ *   locales: ['en', 'es'],
+ *   defaultLocale: 'en',
+ *   routing: 'domain',
+ *   domains: {
+ *     en: 'example.com',
+ *     es: 'es.example.com',
+ *   },
+ * });
+ *
+ * // Custom locale detection
+ * export const middleware = createI18nMiddleware({
+ *   locales: ['en', 'es'],
+ *   defaultLocale: 'en',
+ *   routing: 'cookie',
+ *   detectLocale: (request) => {
+ *     // Check user preferences from session
+ *     return getUserPreferredLocale(request);
+ *   },
+ * });
+ * ```
+ */
+declare function createI18nMiddleware(options: I18nMiddlewareOptions): I18nMiddleware;
+/**
+ * Create a redirect response to a localized URL
+ *
+ * @param request - Original request
+ * @param locale - Target locale
+ * @param config - Routing configuration
+ * @returns Redirect response
+ */
+declare function createLocaleRedirect(request: Request, locale: Locale, config: I18nRoutingConfig): Response;
+
+export { type I18nMiddleware, type I18nMiddlewareOptions, I18nRoutingConfig, Locale, createI18nMiddleware, createLocaleRedirect };

package/dist/middleware.js

@@ -0,0 +1,127 @@
+import {
+  getLocaleFromRequest
+} from "./chunk-F5CV7JNA.js";
+import {
+  buildLocalizedUrl,
+  generateLocaleCookie,
+  matchLocaleFromCookie,
+  matchLocaleFromDomain,
+  matchLocaleFromPath,
+  shouldIgnorePath
+} from "./chunk-O3FQ7FPU.js";
+
+// src/middleware.ts
+function createI18nMiddleware(options) {
+  const {
+    locales,
+    defaultLocale,
+    routing = "none",
+    prefixDefault = false,
+    domains,
+    cookieName = "FLIGHT_LOCALE",
+    cookieMaxAge = 365 * 24 * 60 * 60,
+    ignorePaths,
+    redirectOnMissingLocale = true,
+    detectLocale,
+    onLocaleResolved
+  } = options;
+  const config = {
+    locales,
+    defaultLocale,
+    routing,
+    prefixDefault,
+    domains,
+    cookieName,
+    cookieMaxAge,
+    ignorePaths
+  };
+  return async function i18nMiddleware(request) {
+    const url = new URL(request.url);
+    const { pathname, hostname } = url;
+    if (shouldIgnorePath(pathname, config)) {
+      return null;
+    }
+    let detectedLocale = null;
+    let shouldSetCookie = false;
+    if (detectLocale) {
+      detectedLocale = await detectLocale(request);
+    }
+    if (!detectedLocale) {
+      switch (routing) {
+        case "prefix": {
+          const match = matchLocaleFromPath(pathname, config);
+          if (match.hasLocalePrefix) {
+            detectedLocale = match.locale;
+          }
+          break;
+        }
+        case "domain": {
+          detectedLocale = matchLocaleFromDomain(hostname, config);
+          break;
+        }
+        case "cookie": {
+          const cookieHeader = request.headers.get("Cookie");
+          detectedLocale = matchLocaleFromCookie(cookieHeader, config);
+          break;
+        }
+        case "none":
+        default:
+          break;
+      }
+    }
+    if (!detectedLocale && routing !== "cookie") {
+      const cookieHeader = request.headers.get("Cookie");
+      detectedLocale = matchLocaleFromCookie(cookieHeader, config);
+    }
+    if (!detectedLocale) {
+      detectedLocale = getLocaleFromRequest(request, locales, defaultLocale);
+      if (routing === "prefix" || routing === "cookie") {
+        shouldSetCookie = true;
+      }
+    }
+    if (routing === "prefix" && redirectOnMissingLocale) {
+      const match = matchLocaleFromPath(pathname, config);
+      const needsRedirect = (
+        // No locale prefix, but we detect a non-default locale
+        !match.hasLocalePrefix && detectedLocale !== defaultLocale || // No locale prefix, default locale, but prefixDefault is true
+        !match.hasLocalePrefix && detectedLocale === defaultLocale && prefixDefault
+      );
+      if (needsRedirect) {
+        const newPathname = buildLocalizedUrl(pathname, detectedLocale, config);
+        const newUrl = new URL(newPathname, request.url);
+        newUrl.search = url.search;
+        const response = new Response(null, {
+          status: 307,
+          // Temporary redirect (preserves method)
+          headers: { Location: newUrl.toString() }
+        });
+        response.headers.set("Set-Cookie", generateLocaleCookie(detectedLocale, config));
+        return response;
+      }
+    }
+    if (onLocaleResolved) {
+      await onLocaleResolved(detectedLocale, request);
+    }
+    if (routing === "cookie" && shouldSetCookie) {
+    }
+    return null;
+  };
+}
+function createLocaleRedirect(request, locale, config) {
+  const url = new URL(request.url);
+  const match = matchLocaleFromPath(url.pathname, config);
+  const cleanPathname = match.pathname;
+  const newPathname = buildLocalizedUrl(cleanPathname, locale, config);
+  const newUrl = new URL(newPathname, request.url);
+  newUrl.search = url.search;
+  const response = new Response(null, {
+    status: 307,
+    headers: { Location: newUrl.toString() }
+  });
+  response.headers.set("Set-Cookie", generateLocaleCookie(locale, config));
+  return response;
+}
+export {
+  createI18nMiddleware,
+  createLocaleRedirect
+};

package/dist/routing.d.ts

@@ -0,0 +1,179 @@
+import { Locale } from './index.js';
+
+/**
+ * First-Class i18n Routing for Flight Framework
+ *
+ * Provides configurable routing strategies for internationalized applications:
+ * - 'prefix': URL path prefix (/en/about, /es/about)
+ * - 'domain': Subdomain-based (en.example.com, es.example.com)
+ * - 'cookie': Cookie-based locale persistence (no URL change)
+ * - 'none': No automatic routing (manual control)
+ *
+ * @example
+ * ```typescript
+ * // flight.config.ts
+ * export default defineConfig({
+ *   i18n: {
+ *     locales: ['en', 'es', 'fr'],
+ *     defaultLocale: 'en',
+ *     routing: 'prefix',      // 'prefix' | 'domain' | 'cookie' | 'none'
+ *     prefixDefault: false,   // /about for 'en', /es/about for 'es'
+ *   },
+ * });
+ * ```
+ *
+ * @module @flightdev/i18n/routing
+ */
+
+/**
+ * Available routing strategies for i18n
+ *
+ * - `prefix`: Locale is part of URL path (e.g., /en/about, /es/about)
+ * - `domain`: Locale is determined by domain/subdomain (e.g., en.example.com)
+ * - `cookie`: Locale is stored in a cookie, URL remains unchanged
+ * - `none`: No automatic routing, full manual control (default)
+ */
+type I18nRoutingStrategy = 'prefix' | 'domain' | 'cookie' | 'none';
+/**
+ * Configuration for i18n routing
+ */
+interface I18nRoutingConfig {
+    /** Supported locales (e.g., ['en', 'es', 'fr']) */
+    locales: Locale[];
+    /** Default locale when none is detected */
+    defaultLocale: Locale;
+    /** Routing strategy (default: 'none') */
+    routing?: I18nRoutingStrategy;
+    /** Whether to include prefix for default locale in 'prefix' strategy */
+    prefixDefault?: boolean;
+    /**
+     * Domain mapping for 'domain' strategy
+     * @example { en: 'en.example.com', es: 'es.example.com' }
+     */
+    domains?: Record<Locale, string>;
+    /** Cookie name for 'cookie' strategy (default: 'FLIGHT_LOCALE') */
+    cookieName?: string;
+    /** Cookie max age in seconds (default: 31536000 = 1 year) */
+    cookieMaxAge?: number;
+    /**
+     * Paths to ignore (static assets, API routes, etc.)
+     * Supports strings (prefix match) and RegExp
+     */
+    ignorePaths?: (string | RegExp)[];
+}
+/**
+ * Result of matching a locale from a URL path
+ */
+interface I18nRouteMatch {
+    /** Detected locale */
+    locale: Locale;
+    /** Pathname without locale prefix */
+    pathname: string;
+    /** Whether this is the default locale */
+    isDefault: boolean;
+    /** Whether the URL had an explicit locale prefix */
+    hasLocalePrefix: boolean;
+}
+declare const DEFAULT_CONFIG: Required<Omit<I18nRoutingConfig, 'locales' | 'defaultLocale' | 'domains'>>;
+/**
+ * Match locale from URL pathname (prefix strategy)
+ *
+ * @param pathname - URL pathname (e.g., '/es/about')
+ * @param config - Routing configuration
+ * @returns Route match result
+ *
+ * @example
+ * ```typescript
+ * const match = matchLocaleFromPath('/es/about', config);
+ * // { locale: 'es', pathname: '/about', isDefault: false, hasLocalePrefix: true }
+ * ```
+ */
+declare function matchLocaleFromPath(pathname: string, config: I18nRoutingConfig): I18nRouteMatch;
+/**
+ * Match locale from hostname (domain strategy)
+ *
+ * @param hostname - Request hostname (e.g., 'es.example.com')
+ * @param config - Routing configuration
+ * @returns Matched locale
+ *
+ * @example
+ * ```typescript
+ * const locale = matchLocaleFromDomain('es.example.com', config);
+ * // 'es'
+ * ```
+ */
+declare function matchLocaleFromDomain(hostname: string, config: I18nRoutingConfig): Locale;
+/**
+ * Match locale from cookie header
+ *
+ * @param cookieHeader - Cookie header value
+ * @param config - Routing configuration
+ * @returns Matched locale or null if not found
+ *
+ * @example
+ * ```typescript
+ * const locale = matchLocaleFromCookie('FLIGHT_LOCALE=es; other=value', config);
+ * // 'es'
+ * ```
+ */
+declare function matchLocaleFromCookie(cookieHeader: string | null, config: I18nRoutingConfig): Locale | null;
+/**
+ * Build a localized URL based on routing strategy
+ *
+ * @param pathname - Original pathname
+ * @param locale - Target locale
+ * @param config - Routing configuration
+ * @returns Localized URL
+ *
+ * @example
+ * ```typescript
+ * // Prefix strategy
+ * buildLocalizedUrl('/about', 'es', config);
+ * // '/es/about'
+ *
+ * // Domain strategy
+ * buildLocalizedUrl('/about', 'es', configWithDomains);
+ * // 'https://es.example.com/about'
+ * ```
+ */
+declare function buildLocalizedUrl(pathname: string, locale: Locale, config: I18nRoutingConfig): string;
+/**
+ * Remove locale prefix from pathname
+ *
+ * @param pathname - Pathname possibly containing locale prefix
+ * @param config - Routing configuration
+ * @returns Pathname without locale prefix
+ */
+declare function removeLocalePrefix(pathname: string, config: I18nRoutingConfig): string;
+/**
+ * Get all alternate URLs for a given page (for SEO hreflang)
+ *
+ * @param pathname - Original pathname (without locale prefix)
+ * @param config - Routing configuration
+ * @returns Map of locale to URL
+ *
+ * @example
+ * ```typescript
+ * const alternates = getAlternateUrls('/about', config);
+ * // { en: '/about', es: '/es/about', fr: '/fr/about' }
+ * ```
+ */
+declare function getAlternateUrls(pathname: string, config: I18nRoutingConfig): Record<Locale, string>;
+/**
+ * Check if a path should be ignored by i18n routing
+ *
+ * @param pathname - URL pathname
+ * @param config - Routing configuration
+ * @returns Whether the path should be ignored
+ */
+declare function shouldIgnorePath(pathname: string, config: I18nRoutingConfig): boolean;
+/**
+ * Generate Set-Cookie header value for locale
+ *
+ * @param locale - Locale to set
+ * @param config - Routing configuration
+ * @returns Cookie header value
+ */
+declare function generateLocaleCookie(locale: Locale, config: I18nRoutingConfig): string;
+
+export { type I18nRouteMatch, type I18nRoutingConfig, type I18nRoutingStrategy, Locale, buildLocalizedUrl, DEFAULT_CONFIG as defaultRoutingConfig, generateLocaleCookie, getAlternateUrls, matchLocaleFromCookie, matchLocaleFromDomain, matchLocaleFromPath, removeLocalePrefix, shouldIgnorePath };

package/dist/routing.js

@@ -0,0 +1,22 @@
+import {
+  DEFAULT_CONFIG,
+  buildLocalizedUrl,
+  generateLocaleCookie,
+  getAlternateUrls,
+  matchLocaleFromCookie,
+  matchLocaleFromDomain,
+  matchLocaleFromPath,
+  removeLocalePrefix,
+  shouldIgnorePath
+} from "./chunk-O3FQ7FPU.js";
+export {
+  buildLocalizedUrl,
+  DEFAULT_CONFIG as defaultRoutingConfig,
+  generateLocaleCookie,
+  getAlternateUrls,
+  matchLocaleFromCookie,
+  matchLocaleFromDomain,
+  matchLocaleFromPath,
+  removeLocalePrefix,
+  shouldIgnorePath
+};