vike-i18n-routing 0.1.0

package/README.md

@@ -0,0 +1,450 @@
+<div align="center">
+
+# vike-i18n-routing
+
+<p>
+  <strong>I18n routing for Vike with localized URLs, locale prefixes, domain-aware config, and URL helpers.</strong>
+</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/vike-i18n-routing"><img alt="npm version" src="https://img.shields.io/npm/v/vike-i18n-routing"></a>
+  <a href="https://www.npmjs.com/package/vike-i18n-routing"><img alt="npm downloads" src="https://img.shields.io/npm/dm/vike-i18n-routing"></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="https://github.com/vad1ym/vike-i18n-routing/actions"><img alt="build status" src="https://img.shields.io/github/actions/workflow/status/vad1ym/vike-i18n-routing/publish.yml"></a>
+</p>
+
+</div>
+
+I18n routing for [Vike](https://vike.dev/) with locale prefixes, translated route paths, locale detection, domain-aware locale configuration, and URL helpers.
+
+This package lets you keep one canonical route structure inside your app while exposing localized URLs such as:
+
+- `/en/about`
+- `/ru/o-nas`
+- `/fr/a-propos`
+
+It resolves incoming localized URLs back to one canonical route, redirects invalid locale/path combinations to the correct URL, and exposes helpers to build localized URLs anywhere in your app.
+
+## Status
+
+> [!WARNING]
+> This package is currently under development and should be treated as a proof of concept.
+> The API, behavior, and configuration shape may still change while the project is being validated.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Configuration](#configuration)
+- [Dynamic Routes](#dynamic-routes)
+- [Slug Variants](#slug-variants)
+- [Domain-Based Locale Config](#domain-based-locale-config)
+- [Locale Detection](#locale-detection)
+- [Cookie Behavior](#cookie-behavior)
+- [Runtime Helpers](#runtime-helpers)
+- [Page Context](#page-context)
+- [Example](#example)
+- [Development](#development)
+- [Current Scope](#current-scope)
+- [License](#license)
+
+## Features
+
+- Locale-prefixed routing for Vike
+- Translated static routes like `/about` -> `/o-nas`
+- Dynamic route patterns via `path-to-regexp`
+- Optional segments, for example `/services/:category{/:tab}`
+- Locale detection from URL params, cookies, session, and `Accept-Language`
+- Automatic locale cookie persistence
+- Per-domain locale config
+- URL helpers for canonical URLs, alternates, and localized links
+- Slug variant support for dynamic params
+
+## Installation
+
+Choose your package manager:
+
+```bash
+pnpm add vike-i18n-routing
+```
+
+```bash
+npm install vike-i18n-routing
+```
+
+```bash
+yarn add vike-i18n-routing
+```
+
+Peer dependency:
+
+- `vike >= 0.4.259`
+
+## Quick Start
+
+Extend your Vike config with the plugin config and provide an `i18n` definition.
+
+```ts
+// Result:
+// /en/about
+// /ru/o-nas
+// /fr/a-propos
+```
+
+```ts
+// pages/+config.ts
+import vikeVue from 'vike-vue/config'
+import vikeI18n from 'vike-i18n-routing/config'
+import type { Config } from 'vike/types'
+import type { I18nConfig } from 'vike-i18n-routing'
+
+export default {
+  extends: [vikeVue, vikeI18n],
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'ru'],
+    prefixDefaultLocale: true,
+    routes: {
+      '/': { en: '/', ru: '/' },
+      '/about': { en: '/about', ru: '/o-nas' },
+    },
+  } satisfies I18nConfig,
+} satisfies Config
+```
+
+With that config:
+
+- `/en/about` resolves to canonical route `/about`
+- `/ru/o-nas` resolves to canonical route `/about`
+- `/about` redirects to `/en/about`
+- `/ru/about` redirects to `/ru/o-nas`
+
+Your page files still use the canonical route structure:
+
+```text
+pages/
+  index/+Page.vue
+  about/+Page.vue
+```
+
+## How It Works
+
+The plugin runs in `onBeforeRoute` and:
+
+1. Detects the active locale
+2. Resolves the incoming localized path to a canonical route path
+3. Redirects to the correct localized URL when needed
+4. Exposes `pageContext.locale` and `pageContext.canonical`
+
+It also writes the resolved locale to a cookie during render unless cookie support is disabled.
+
+> [!TIP]
+> Your actual page files stay canonical. Only the public URLs are localized.
+
+## Configuration
+
+### `I18nConfig`
+
+```ts
+type I18nConfig = {
+  defaultLocale: string
+  locales: string[] | Record<string, { urlPrefix: string }>
+  routes: Record<string, Record<string, string>>
+  prefixDefaultLocale?: boolean
+  domains?: Record<string, DomainConfig>
+  domainDetector?: (context: DetectorContext) => string | null | undefined
+  localeDetector?: (context: DetectorContext) => string | null | undefined
+  localeCookie?: string | false
+}
+```
+
+### Locales
+
+Simple array form:
+
+```ts
+locales: ['en', 'ru', 'fr']
+```
+
+Object form when you want explicit URL prefixes:
+
+```ts
+locales: {
+  en: { urlPrefix: 'en' },
+  ru: { urlPrefix: 'ru' },
+  fr: { urlPrefix: 'fr' },
+}
+```
+
+### Routes
+
+Route keys are canonical app routes. Values are locale-specific public URLs.
+
+This means your code can keep using one stable route key while users see translated URLs.
+
+```ts
+routes: {
+  '/': {
+    en: '/',
+    ru: '/',
+    fr: '/',
+  },
+  '/about': {
+    en: '/about',
+    ru: '/o-nas',
+    fr: '/a-propos',
+  },
+}
+```
+
+### `prefixDefaultLocale`
+
+When `true`:
+
+- `/about` redirects to `/en/about`
+
+When `false`:
+
+- `/about` stays `/about`
+- `/en/about` redirects back to `/about`
+
+## Dynamic Routes
+
+Dynamic patterns are supported through `path-to-regexp`.
+
+```ts
+routes: {
+  '/services/:category{/:tab}': {
+    en: '/services/:category{/:tab}',
+    ru: '/uslugi/:category{/:tab}',
+    fr: '/services-fr/:category{/:tab}',
+  },
+}
+```
+
+Examples:
+
+- `/ru/uslugi/design` -> canonical `/services/design`
+- `/ru/uslugi/design/specs` -> canonical `/services/design/specs`
+
+> [!NOTE]
+> Dynamic route matching and generation are powered by `path-to-regexp`.
+
+## Slug Variants
+
+Use `setRouteSlugVariants()` when a dynamic param should have locale-specific slug values.
+
+```ts
+import { setRouteSlugVariants } from 'vike-i18n-routing'
+
+setRouteSlugVariants('category', {
+  en: 'web-development',
+  ru: 'veb-razrabotka',
+  fr: 'developpement-web',
+})
+```
+
+Then:
+
+- canonical `/services/web-development`
+- RU localized `/ru/uslugi/veb-razrabotka`
+- FR localized `/services-fr/developpement-web`
+
+## Domain-Based Locale Config
+
+You can override locales and default locale per domain.
+
+```ts
+i18n: {
+  defaultLocale: 'en',
+  locales: ['en', 'ru', 'fr'],
+  prefixDefaultLocale: true,
+  domains: {
+    'site.com': {
+      defaultLocale: 'en',
+      locales: ['en', 'ru'],
+    },
+    'site.fr': {
+      defaultLocale: 'fr',
+      locales: ['fr', 'en'],
+      prefixDefaultLocale: false,
+      meta: {
+        supportedAuthCountries: ['fr', 'uk', 'ru'],
+      },
+    },
+  },
+  routes: {
+    '/': { en: '/', ru: '/', fr: '/' },
+    '/about': { en: '/about', ru: '/o-nas', fr: '/a-propos' },
+  },
+}
+```
+
+The resolved domain metadata is exposed on `pageContext.i18nDomain`.
+
+## Locale Detection
+
+For unprefixed requests, locale resolution checks candidates in this order:
+
+1. Custom `localeDetector(context)`
+2. `?locale=...`
+3. `?lang=...`
+4. Locale cookie
+5. `session.locale`
+6. `Accept-Language`
+7. `defaultLocale`
+
+This keeps unprefixed requests usable while still normalizing users onto the correct localized URL shape.
+
+You can also override domain detection:
+
+```ts
+domainDetector(context) {
+  return context.headers.host as string
+}
+```
+
+## Cookie Behavior
+
+By default, the plugin stores the active locale in a cookie named `i18n-locale`.
+
+Set a custom name:
+
+```ts
+localeCookie: 'locale'
+```
+
+Disable cookie writes entirely:
+
+```ts
+localeCookie: false
+```
+
+The default cookie name is `i18n-locale`.
+
+## Runtime Helpers
+
+```ts
+import {
+  createI18nRouter,
+  getAlternates,
+  resolveCanonical,
+  resolveI18nRoute,
+  setRouteSlugVariants,
+  toCanonicalUrl,
+  toLocalizedUrl,
+  toRouteUrl,
+} from 'vike-i18n-routing'
+```
+
+### `toLocalizedUrl()`
+
+```ts
+toLocalizedUrl('/about', 'ru', i18n)
+// /ru/o-nas
+```
+
+You can also omit the locale and let it infer from the current URL/context:
+
+```ts
+toLocalizedUrl('/about', i18n, { context })
+```
+
+### `toCanonicalUrl()`
+
+```ts
+toCanonicalUrl('/ru/o-nas', i18n)
+// /en/about   when prefixDefaultLocale === true
+```
+
+### `toRouteUrl()`
+
+```ts
+toRouteUrl('/ru/o-nas', i18n)
+// /about
+```
+
+### `getAlternates()`
+
+```ts
+getAlternates('/about', i18n, { context })
+// [
+//   { locale: 'en', url: '/en/about' },
+//   { locale: 'ru', url: '/ru/o-nas' }
+// ]
+```
+
+### `createI18nRouter()`
+
+Create a reusable router instance if you want to resolve/build URLs repeatedly:
+
+```ts
+const router = createI18nRouter(i18n)
+
+router.resolve('/ru/o-nas', { context })
+router.resolveCanonical('/ru/o-nas', context)
+router.resolveLocalizedPath('/about', 'ru', context)
+router.getAlternates('/about', context)
+```
+
+## Page Context
+
+The plugin adds:
+
+- `pageContext.locale`
+- `pageContext.canonical`
+- `pageContext.i18nDomain`
+
+Example:
+
+```ts
+const locale = pageContext.locale
+const canonicalRoute = pageContext.canonical
+```
+
+## Example
+
+A basic example app is available in [`examples/basic`](./examples/basic).
+
+Run it with:
+
+```bash
+pnpm example
+```
+
+## Development
+
+```bash
+pnpm test
+pnpm typecheck
+```
+
+## Current Scope
+
+This package currently focuses on:
+
+- Vike route resolution
+- Localized path generation
+- Redirect normalization
+- Per-domain locale rules
+- Cookie-backed locale persistence
+
+It does not yet include built-in HTML SEO tag generation or full documentation site tooling.
+
+## Why This Package
+
+If you want Vike routes to:
+
+- stay canonical in your app code
+- render translated public URLs per locale
+- redirect users to the correct locale/path combination
+- support domain-specific locale rules
+
+this package is the layer that handles that routing logic.
+
+## License
+
+MIT

package/lib/core/cookies.ts

@@ -0,0 +1,21 @@
+import type { I18nConfig, LocaleCookieAction } from './types'
+
+const DEFAULT_COOKIE_NAME = 'i18n-locale'
+
+// Resolves the cookie write action for the current locale.
+export function resolveCookieAction(
+  locale: string,
+  i18n: I18nConfig,
+): LocaleCookieAction | null {
+  if (i18n.localeCookie === false) return null
+
+  return {
+    name: i18n.localeCookie ?? DEFAULT_COOKIE_NAME,
+    value: locale,
+  }
+}
+
+// Serializes the locale cookie action into a Set-Cookie header value.
+export function createSetCookieHeader(action: LocaleCookieAction): string {
+  return `${action.name}=${encodeURIComponent(action.value)}; Path=/; SameSite=Lax; HttpOnly`
+}

package/lib/core/domain/detector.ts

@@ -0,0 +1,18 @@
+import type { DetectorContext, I18nConfig } from '../types'
+
+// Resolves the current domain from a custom detector, explicit context, or request host.
+export function detectDomain(context: DetectorContext, i18n: I18nConfig): string | undefined {
+  const custom = i18n.domainDetector?.(context)
+  if (custom) return custom.toLowerCase()
+  if (context.domain) return context.domain.toLowerCase()
+
+  const hostHeader = context.headers.host
+  const host = Array.isArray(hostHeader) ? hostHeader[0] : hostHeader
+  if (host) return host.split(':')[0].toLowerCase()
+
+  try {
+    return new URL(context.url, 'http://localhost').hostname.toLowerCase() || undefined
+  } catch {
+    return undefined
+  }
+}

package/lib/core/domain/normalize.ts

@@ -0,0 +1,25 @@
+import { detectDomain } from './detector'
+import { normalizeLocales } from '../locale/normalize'
+import type { DetectorContext, I18nConfig, ResolvedDomainConfig } from '../types'
+
+// Resolves the effective domain config by combining global defaults with domain overrides.
+export function resolveDomainConfig(
+  i18n: I18nConfig,
+  context: DetectorContext,
+): ResolvedDomainConfig {
+  const baseLocales = normalizeLocales(i18n.locales)
+  const domain = detectDomain(context, i18n)
+  const domainConfig = domain ? i18n.domains?.[domain] : undefined
+  const locales = domainConfig?.locales
+    ? normalizeLocales(domainConfig.locales)
+    : baseLocales
+  const defaultLocale = domainConfig?.defaultLocale ?? i18n.defaultLocale
+
+  return {
+    domain,
+    defaultLocale,
+    locales,
+    prefixDefaultLocale: domainConfig?.prefixDefaultLocale ?? i18n.prefixDefaultLocale !== false,
+    meta: domainConfig?.meta,
+  }
+}

package/lib/core/locale/detector.ts

@@ -0,0 +1,80 @@
+import { resolveDomainConfig } from '../domain/normalize'
+import { normalizeLocales } from './normalize'
+import type { DetectorContext, I18nConfig, LocaleCode } from '../types'
+
+// Parses a Cookie header string into a name/value map.
+export function parseCookies(cookieHeader: string): Record<string, string> {
+  return Object.fromEntries(
+    cookieHeader
+      .split(';')
+      .map((part) => part.trim().split('='))
+      .filter(([key]) => key)
+      .map(([key, ...rest]) => [key.trim(), decodeURIComponent(rest.join('=').trim())]),
+  )
+}
+
+// Parses Accept-Language into locale candidates ordered by quality value.
+function parseAcceptLanguage(header: string | undefined): string[] {
+  if (!header) return []
+
+  return header
+    .split(',')
+    .map((part) => {
+      const [tag, qValue] = part.trim().split(';q=')
+      return {
+        locale: tag.toLowerCase(),
+        weight: qValue ? Number(qValue) : 1,
+      }
+    })
+    .filter((item) => item.locale)
+    .sort((a, b) => b.weight - a.weight)
+    .flatMap((item) => {
+      const base = item.locale.split('-')[0]
+      return base && base !== item.locale ? [item.locale, base] : [item.locale]
+    })
+}
+
+// Reads the configured locale cookie from the request context.
+function resolveCookieLocale(context: DetectorContext, i18n: I18nConfig): string | undefined {
+  if (i18n.localeCookie === false) return undefined
+  const cookieName = i18n.localeCookie ?? 'i18n-locale'
+  return context.cookies[cookieName]
+}
+
+// Resolves the best locale for an unprefixed request.
+export function runLocaleDetector(
+  context: DetectorContext,
+  i18n: I18nConfig,
+): LocaleCode {
+  const resolvedDomain = resolveDomainConfig(i18n, context)
+  const locales = normalizeLocales(resolvedDomain.locales)
+
+  const validate = (locale: string | null | undefined): LocaleCode | null => {
+    if (locale && locales[locale]) return locale
+    return null
+  }
+
+  const candidates: Array<string | null | undefined> = []
+
+  if (i18n.localeDetector) {
+    candidates.push(i18n.localeDetector(context))
+  }
+
+  candidates.push(
+    context.searchParams.get('locale'),
+    context.searchParams.get('lang'),
+    resolveCookieLocale(context, i18n),
+    context.session?.locale,
+  )
+
+  const acceptLanguage = context.headers['accept-language']
+  const headerValue = Array.isArray(acceptLanguage) ? acceptLanguage[0] : acceptLanguage
+  candidates.push(...parseAcceptLanguage(headerValue))
+
+  for (const candidate of candidates) {
+    const detected = validate(candidate)
+    if (detected) return detected
+  }
+
+  return resolvedDomain.defaultLocale
+}

package/lib/core/locale/normalize.ts

@@ -0,0 +1,10 @@
+import type { LocaleCode, LocaleConfig, LocaleConfigs } from '../types'
+
+// Normalizes locale config to the internal record form.
+export function normalizeLocales(locales: LocaleConfigs): Record<LocaleCode, LocaleConfig> {
+  if (Array.isArray(locales)) {
+    return Object.fromEntries(locales.map((code) => [code, { urlPrefix: code }]))
+  }
+
+  return locales
+}

package/lib/core/resolve.ts

@@ -0,0 +1,39 @@
+import { createI18nRouter, setRouteSlugVariants } from './router'
+import type {
+  DetectorContext,
+  I18nConfig,
+  LocaleCode,
+  LocalizedPathOptions,
+  ResolveRouteOptions,
+} from './types'
+
+export { setRouteSlugVariants }
+
+// Resolves an incoming pathname to locale, canonical route, and redirect metadata.
+export function resolveI18nRoute(
+  pathname: string,
+  i18n: I18nConfig,
+  options: ResolveRouteOptions,
+) {
+  return createI18nRouter(i18n).resolve(pathname, options)
+}
+
+// Resolves any pathname to its canonical route URL without locale prefixing.
+export function resolveCanonical(
+  pathname: string,
+  i18n: I18nConfig,
+  options: { context: DetectorContext },
+): string {
+  return createI18nRouter(i18n).resolveCanonical(pathname, options.context)
+}
+
+// Converts a canonical route key into the concrete localized pathname for a locale.
+export function resolveLocalizedPath(
+  routeKey: string,
+  locale: LocaleCode,
+  i18n: I18nConfig,
+  context: DetectorContext,
+  options?: LocalizedPathOptions,
+): string {
+  return createI18nRouter(i18n).resolveLocalizedPath(routeKey, locale, context, options)
+}