Merge pull request #9 from eremannisto/error-pages

Feature: Improve `404` page handling and `hybrid` mode

Author: eremannisto

README.md

@@ -11,8 +11,8 @@ A full-featured i18n integration for Astro. Handles locale detection, URL routin
 ## Installation
 
 ```bash
-npm install @mannisto/astro-i18n
 pnpm add @mannisto/astro-i18n
+npm install @mannisto/astro-i18n
 yarn add @mannisto/astro-i18n
 ```
 
@@ -42,8 +42,6 @@ See the full [Configuration reference](#configuration) below.
 
 ## Modes
 
-The `mode` option controls how pages are rendered and how locale detection works.
-
 ### Static
 
 Pages prebuilt at build time, locale detection at the root via a small inline script.
@@ -59,9 +57,9 @@ Pages rendered on demand, middleware handles all locale detection and redirects.
 - No flash on first visit
 - Supports unprefixed URL rewrites (e.g. `/about` → `/en/about`)
 
-### Hybrid
+### Hybrid (Recommended)
 
-Recommended. Pages prerendered for performance, with a server-rendered catch-all route handling root detection and unprefixed URL redirects.
+Pages prerendered for performance, with a server-rendered catch-all route handling root detection and unprefixed URL redirects.
 
 - Requires a Node adapter
 - Best of both worlds: static performance with server-side locale handling
@@ -84,14 +82,14 @@ All locale files must define the same set of keys.
 
 ### Pages
 
+In `static` and `hybrid` mode, use `getStaticPaths` to prerender pages for each locale:
+
 ```astro
 ---
 import { Locale } from "@mannisto/astro-i18n/runtime"
 
 export const getStaticPaths = () => {
-  return Locale.supported.map((code) => (
-    { params: { locale: code } }
-  ))
+  return Locale.supported.map((code) => ({ params: { locale: code } }))
 }
 
 const locale = Locale.from(Astro.url)
@@ -110,11 +108,24 @@ const t = Locale.use(locale)
 </html>
 ```
 
-> **Note:** In `server` mode, omit `getStaticPaths` — pages are rendered on demand.
+In `server` mode, omit `getStaticPaths` and opt out of prerendering explicitly:
+
+```astro
+---
+export const prerender = false
+
+import { Locale } from "@mannisto/astro-i18n/runtime"
+
+const locale = Locale.from(Astro.url)
+const t = Locale.use(locale)
+---
+```
+
+Without `prerender = false`, Astro will treat dynamic routes as static and throw a `GetStaticPathsRequired` error even in server mode.
 
 ### Layout
 
-Your layout should derive the locale from the URL and sync it to a cookie on every page load. This ensures the correct locale is remembered across visits.
+Your layout should derive the locale from the URL and sync it to a cookie on every page load. This ensures the correct locale is remembered across visits and that 404 pages detect the locale correctly.
 
 ```astro
 ---
@@ -137,6 +148,25 @@ const locale = Locale.from(Astro.url)
 </html>
 ```
 
+### 404 pages
+
+Create a `src/pages/404.astro` at the root. In `hybrid` and `server` mode, unknown paths are redirected to their locale-prefixed equivalent before the 404 renders (e.g. `/banana` → `/en/banana`), so `Locale.from(Astro.url)` always returns the correct locale. In `static` mode, `Locale.from` falls back to `defaultLocale` for bare unprefixed paths, but locale-prefixed paths like `/fi/banana` still resolve correctly.
+
+```astro
+---
+import { Locale } from "@mannisto/astro-i18n/runtime"
+import Layout from "@layouts/Layout.astro"
+
+const locale = Locale.from(Astro.url)
+const t = Locale.use(locale)
+---
+
+<Layout title={t("error.title")}>
+  <h1>{t("error.title")}</h1>
+  <p>{t("error.description")}</p>
+</Layout>
+```
+
 ### Language switcher
 
 ```astro
@@ -164,9 +194,9 @@ const locales = Locale.get()
 </script>
 ```
 
-### Middleware (server mode)
+### Middleware
 
-The middleware is auto-registered in `server` mode. It redirects unprefixed URLs (e.g. `/about` → `/en/about`) and keeps the locale cookie in sync.
+The middleware is auto-registered in `server` and `hybrid` mode. It redirects unprefixed URLs (e.g. `/about` → `/en/about`), keeps the locale cookie in sync, and automatically skips prerendered pages to avoid warnings about unavailable request headers.
 
 You can also compose it manually with other middleware:
 
@@ -179,39 +209,37 @@ import { onRequest as myMiddleware } from "./my-middleware"
 export const onRequest = sequence(i18nMiddleware, myMiddleware)
 ```
 
-> **Note:** In `hybrid` mode, unprefixed URL redirects are handled by an injected catch-all route, not middleware.
-
 ## API
 
 ### Locale
 
 ```typescript
-Locale.supported         // ["en", "fi"] — array of all locale codes
-Locale.defaultLocale     // "en"
-Locale.get()             // all locale configs
-Locale.get("fi")         // { code: "fi", name: "Finnish", endonym: "Suomi", ... }
-Locale.from(Astro.url)   // "fi" — derives current locale from URL
+Locale.supported       // ["en", "fi"] — array of all locale codes
+Locale.defaultLocale   // "en"
+Locale.get()           // all locale configs
+Locale.get("fi")       // { code: "fi", name: "Finnish", endonym: "Suomi", ... }
+Locale.from(Astro.url) // "fi" — derives current locale from URL
 ```
 
 ### Translations
 
 ```typescript
 const t = Locale.use(locale)
-t("nav.home")            // "Home"
+t("nav.home") // "Home"
 ```
 
 ### URL helpers
 
 ```typescript
-Locale.url("fi")                      // "/fi/"
-Locale.url("fi", "/about")            // "/fi/about"
-Locale.url("fi", Astro.url.pathname)  // "/fi/current-path"
+Locale.url("fi")                     // "/fi/"
+Locale.url("fi", "/about")           // "/fi/about"
+Locale.url("fi", Astro.url.pathname) // "/fi/current-path"
 ```
 
 ### Switching locale
 
 ```typescript
-Locale.switch("fi")  // sets cookie and redirects to the equivalent page in the new locale
+Locale.switch("fi") // sets cookie and navigates to the equivalent page in the new locale
 ```
 
 ## Configuration
@@ -237,11 +265,15 @@ i18n({
   // Path to translation JSON files — omit to disable translations
   translations: "./src/translations",
 
-  // URL paths to bypass the middleware — server mode only
+  // URL paths to bypass the middleware — server and hybrid mode only
   ignore: ["/keystatic", "/api"],
 })
 ```
 
+## Development
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, testing, and publishing instructions.
+
 ## License
 
 MIT © [Ere Männistö](https://github.com/eremannisto)

dist/index.js

@@ -75,25 +75,6 @@ var Validate = {
     if (fs.existsSync(indexPath)) {
       throw new Error(`${NAME} Found conflicting src/pages/index.astro \u2014 remove it.`);
     }
-  },
-  /**
-   * Validates that there is no conflicting catch-all route when mode is
-   * "hybrid". A [...path].astro or [...path].ts would intercept the injected
-   * redirect route.
-   */
-  catchall(root, mode) {
-    if (mode !== "hybrid") return;
-    const candidates = [
-      new URL("./src/pages/[...path].astro", root),
-      new URL("./src/pages/[...path].ts", root)
-    ];
-    for (const candidate of candidates) {
-      if (fs.existsSync(candidate)) {
-        throw new Error(
-          `${NAME} Found conflicting ${candidate.pathname.split("/src/pages/")[1]} \u2014 remove it or switch to "server" mode.`
-        );
-      }
-    }
   }
 };
 
@@ -134,7 +115,6 @@ function i18n(config) {
         }
         Validate.config(config);
         Validate.index(astroConfig.root, config.mode);
-        Validate.catchall(astroConfig.root, config.mode);
         resolved = resolveConfig(config);
         updateConfig({
           vite: {
@@ -183,13 +163,8 @@ export const translations = ${JSON.stringify(translationData)}
             entrypoint: "@mannisto/astro-i18n/detect/hybrid",
             prerender: false
           });
-          injectRoute({
-            pattern: "/[...path]",
-            entrypoint: "@mannisto/astro-i18n/redirect/hybrid",
-            prerender: false
-          });
         }
-        if (resolved.mode === "server") {
+        if (resolved.mode === "server" || resolved.mode === "hybrid") {
           addMiddleware({
             entrypoint: "@mannisto/astro-i18n/middleware",
             order: "pre"

dist/middleware.js

@@ -1,24 +1,28 @@
 // src/middleware.ts
 import { defineMiddleware } from "astro/middleware";
 import { config } from "virtual:astro-i18n/config";
-var onRequest = defineMiddleware(({ url, cookies, redirect }, next) => {
-  const pathname = url.pathname;
-  const ignore = config.ignore ?? [];
-  const codes = config.locales.map((l) => l.code);
-  if (ignore.some((path) => pathname.startsWith(path))) return next();
-  if (pathname === "/") return next();
-  const firstSegment = pathname.split("/")[1];
-  if (codes.includes(firstSegment)) {
-    const stored2 = cookies.get("locale")?.value;
-    if (stored2 !== firstSegment) {
-      cookies.set("locale", firstSegment, { path: "/", sameSite: "lax" });
+var onRequest = defineMiddleware(
+  ({ url, cookies, redirect, request, isPrerendered }, next) => {
+    console.log(url.pathname, isPrerendered);
+    if (isPrerendered) return next();
+    const pathname = url.pathname;
+    const ignore = config.ignore ?? [];
+    const codes = config.locales.map((l) => l.code);
+    if (ignore.some((path) => pathname.startsWith(path))) return next();
+    if (pathname === "/") return next();
+    const firstSegment = pathname.split("/")[1];
+    if (codes.includes(firstSegment)) {
+      const stored2 = cookies.get("locale")?.value;
+      if (stored2 !== firstSegment) {
+        cookies.set("locale", firstSegment, { path: "/", sameSite: "lax" });
+      }
+      return next();
     }
-    return next();
+    const stored = cookies.get("locale")?.value;
+    const targetLocale = stored && codes.includes(stored) ? stored : config.defaultLocale;
+    return redirect(`/${targetLocale}${pathname}`, 302);
   }
-  const stored = cookies.get("locale")?.value;
-  const targetLocale = stored && codes.includes(stored) ? stored : config.defaultLocale;
-  return redirect(`/${targetLocale}${pathname}`, 302);
-});
+);
 var i18nMiddleware = onRequest;
 export {
   i18nMiddleware,

dist/redirect/hybrid.d.ts

@@ -1,6 +1,6 @@
 {
   "name": "@mannisto/astro-i18n",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.8",
   "description": "A flexible alternative to Astro's built-in i18n, with locale routing, detection, and translations for static and SSR sites.",
   "license": "MIT",
   "type": "module",
@@ -44,10 +44,6 @@
     "./detect/hybrid": {
       "types": "./dist/detect/hybrid.d.ts",
       "default": "./dist/detect/hybrid.js"
-    },
-    "./redirect/hybrid": {
-      "types": "./dist/redirect/hybrid.d.ts",
-      "default": "./dist/redirect/hybrid.js"
     }
   },
   "typesVersions": {
@@ -66,9 +62,6 @@
       ],
       "detect/hybrid": [
         "./dist/detect/hybrid.d.ts"
-      ],
-      "redirect/hybrid": [
-        "./dist/redirect/hybrid.d.ts"
       ]
     }
   },

dist/redirect/hybrid.js

@@ -45,7 +45,6 @@ export default function i18n(config: I18nConfig): AstroIntegration {
 
         Validate.config(config)
         Validate.index(astroConfig.root, config.mode)
-        Validate.catchall(astroConfig.root, config.mode)
 
         resolved = resolveConfig(config)
 
@@ -95,24 +94,21 @@ export const translations = ${JSON.stringify(translationData)}
           })
         }
 
-        // Hybrid mode — inject a server-side route at / and a catch-all
-        // redirect for unprefixed paths. Only these routes are server-rendered,
-        // all locale pages remain static.
+        // Hybrid mode — inject a server-side route at /
+        // All locale pages remain prerendered static files.
         if (resolved.mode === "hybrid") {
           injectRoute({
             pattern: "/",
             entrypoint: "@mannisto/astro-i18n/detect/hybrid",
             prerender: false,
           })
-          injectRoute({
-            pattern: "/[...path]",
-            entrypoint: "@mannisto/astro-i18n/redirect/hybrid",
-            prerender: false,
-          })
         }
 
-        // Middleware — only registered for server mode
-        if (resolved.mode === "server") {
+        // Middleware — registered for server and hybrid mode.
+        // Handles unprefixed URL redirects and cookie sync.
+        // In hybrid mode, static pages are still served directly by the
+        // adapter — middleware only runs for requests that need redirecting.
+        if (resolved.mode === "server" || resolved.mode === "hybrid") {
           addMiddleware({
             entrypoint: "@mannisto/astro-i18n/middleware",
             order: "pre",

package.json

@@ -95,24 +95,4 @@ export const Validate = {
       throw new Error(`${NAME} Found conflicting src/pages/index.astro — remove it.`)
     }
   },
-
-  /**
-   * Validates that there is no conflicting catch-all route when mode is
-   * "hybrid". A [...path].astro or [...path].ts would intercept the injected
-   * redirect route.
-   */
-  catchall(root: URL, mode: string | undefined): void {
-    if (mode !== "hybrid") return
-    const candidates = [
-      new URL("./src/pages/[...path].astro", root),
-      new URL("./src/pages/[...path].ts", root),
-    ]
-    for (const candidate of candidates) {
-      if (fs.existsSync(candidate)) {
-        throw new Error(
-          `${NAME} Found conflicting ${candidate.pathname.split("/src/pages/")[1]} — remove it or switch to "server" mode.`
-        )
-      }
-    }
-  },
 }