npm - @mannisto/astro-i18n - Versions diffs - 1.0.0-alpha.1 - Mend

@mannisto/astro-i18n 1.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Ere Männistö
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,264 @@
+# Astro Internationalization (i18n)
+![npm version](https://img.shields.io/npm/v/@mannisto/astro-i18n)
+![license](https://img.shields.io/badge/license-MIT-green)
+![astro peer dependency](https://img.shields.io/npm/dependency-version/@mannisto/astro-i18n/peer/astro)
+A flexible alternative to Astro's built-in i18n, with locale routing,
+detection, and translations for static and SSR sites.
+## Features
+- Three detection modes: `server`, `client`, and `none`
+- Automatic locale prefixing via middleware
+- Optional static translation files with key validation
+- Works with Astro's static and SSR output modes
+## Installation
+```bash
+pnpm add @mannisto/astro-i18n
+```
+## Setup
+Add the integration to your `astro.config.ts`:
+```typescript
+import { defineConfig } from "astro/config"
+import i18n from "@mannisto/astro-i18n"
+export default defineConfig({
+  integrations: [
+    i18n({
+      locales: [
+        { code: "en", name: "English", endonym: "English" },
+        { code: "fi", name: "Finnish", endonym: "Suomi", phrase: "Suomeksi" },
+      ],
+      routing: {
+        fallback: "en",
+        detection: "server",
+        autoPrefix: {
+          ignore: ["/keystatic"],
+        },
+      },
+    }),
+  ],
+})
+```
+## Translations
+Translations are optional. To enable them, add a `translations` path to
+your config pointing to a directory with a JSON file for each locale:
+```
+src/translations/
+  en.json
+  fi.json
+```
+```typescript
+i18n({
+  locales: [...],
+  translations: "./src/translations",
+})
+```
+Each file should contain a flat object of key-value pairs:
+```json
+{
+  "nav.home": "Home",
+  "nav.about": "About",
+  "footer.copyright": "All rights reserved"
+}
+```
+All locales must have the same keys as the fallback locale or the
+integration will throw an error at startup. If translations are not
+configured, `Locale.use()` will log a warning when called.
+## Usage
+Import `Locale` from the runtime subpath in your pages and components:
+```astro
+---
+import { Locale } from "@mannisto/astro-i18n/runtime"
+export const getStaticPaths = () =>
+  Locale.supported.map((code) => ({ params: { locale: code } }))
+const { locale } = Astro.params
+const t = Locale.use(locale)
+---
+<html lang={locale}>
+  <body>
+    <h1>{t("nav.home")}</h1>
+  </body>
+</html>
+```
+## API
+### `Locale.supported`
+Returns all supported locale codes.
+```typescript
+Locale.supported // ["en", "fi"]
+```
+### `Locale.fallback`
+Returns the fallback locale code.
+```typescript
+Locale.fallback // "en"
+```
+### `Locale.current(locale)`
+Returns the current locale from `Astro.params`.
+```typescript
+const locale = Locale.current(Astro.params.locale)
+```
+### `Locale.get(code?)`
+Returns the config for all locales, or a single locale by code.
+```typescript
+Locale.get()      // all locales
+Locale.get("fi")  // { code: "fi", name: "Finnish", endonym: "Suomi", ... }
+```
+### `Locale.use(locale)`
+Binds a locale and returns a translation function for that locale.
+Call once at the top of your page, then use the returned function
+to look up individual keys.
+Requires `translations` to be configured. Logs a warning if called
+without translations configured.
+```typescript
+const t = Locale.use(locale)
+t("nav.home")  // "Home"
+t()            // { "nav.home": "Home", ... }
+```
+### `Locale.middleware`
+Middleware that redirects requests without a locale prefix to the correct
+locale based on the user's cookie. Auto-registered when detection is
+`"server"` and `autoPrefix` is enabled.
+Can also be used manually:
+```typescript
+import { sequence } from "astro/middleware"
+import { Locale } from "@mannisto/astro-i18n/runtime"
+export const onRequest = sequence(Locale.middleware, myMiddleware)
+```
+## Detection modes
+### `server`
+Reads the `Accept-Language` header on first visit, sets a cookie, and
+redirects to the appropriate locale URL. Requires an adapter for
+production builds.
+```typescript
+import { defineConfig } from "astro/config"
+import node from "@astrojs/node"
+import i18n from "@mannisto/astro-i18n"
+export default defineConfig({
+  adapter: node({ mode: "standalone" }),
+  integrations: [
+    i18n({
+      locales: [
+        { code: "en", name: "English", endonym: "English" },
+        { code: "fi", name: "Finnish", endonym: "Suomi", phrase: "Suomeksi" },
+      ],
+      routing: {
+        fallback: "en",
+        detection: "server",
+        autoPrefix: {
+          ignore: ["/keystatic"],
+        },
+      },
+    }),
+  ],
+})
+```
+### `client`
+Serves a static HTML page at `/` with an inline JS redirect script that
+reads `navigator.language` and stores the result in `localStorage`.
+Works without an adapter.
+```typescript
+i18n({
+  locales: [
+    { code: "en", name: "English", endonym: "English" },
+    { code: "fi", name: "Finnish", endonym: "Suomi", phrase: "Suomeksi" },
+  ],
+  routing: {
+    fallback: "en",
+    detection: "client",
+  },
+})
+```
+### `none`
+No detection. Users must navigate to a locale URL directly, e.g. `/en/`.
+```typescript
+i18n({
+  locales: [
+    { code: "en", name: "English", endonym: "English" },
+    { code: "fi", name: "Finnish", endonym: "Suomi", phrase: "Suomeksi" },
+  ],
+  routing: {
+    fallback: "en",
+    detection: "none",
+  },
+})
+```
+## Configuration reference
+```typescript
+i18n({
+  // required — list of supported locales
+  locales: [
+    {
+      code: "en",           // locale code used in URLs
+      name: "English",      // locale name in English
+      endonym: "English",   // locale name in its own language
+      phrase: "In English", // optional, for locale switchers
+    },
+  ],
+  routing: {
+    // locale to use when no match is found
+    // defaults to the first locale in the array
+    fallback: "en",
+    // how the user's locale is detected on first visit
+    // "server" | "client" | "none" — defaults to "client"
+    detection: "server",
+    // middleware that prefixes unknown routes with the user's locale
+    // only valid when detection is "server"
+    // set to false to disable, or pass an object to configure ignore paths
+    autoPrefix: {
+      ignore: ["/keystatic", "/api"],
+    },
+  },
+  // optional — path to translation files, relative to the project root
+  // if not set, translations are disabled and Locale.use() will warn when called
+  translations: "./src/translations",
+})
+```
+## Contributing
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+## License
+MIT © [Ere Männistö](https://github.com/eremannisto)

package/dist/chunk-SMGDNPQN.js ADDED Viewed

@@ -0,0 +1,123 @@
+// src/lib/locale.ts
+import { defineMiddleware } from "astro/middleware";
+import { config, translations } from "virtual:astro-i18n/config";
+var NAME = "@mannisto/astro-i18n";
+var Locale = {
+  // ==========================================================================
+  // Locale access
+  // ==========================================================================
+  /**
+   * All supported locale codes.
+   * @example ["en", "fi"]
+   */
+  get supported() {
+    return config.locales.map((l) => l.code);
+  },
+  /**
+   * The fallback locale code.
+   * @example "en"
+   */
+  get fallback() {
+    return config.routing.fallback;
+  },
+  /**
+   * Returns the current locale from Astro.params.
+   * @example
+   * const locale = Locale.current(Astro.params.locale)
+   */
+  current(locale) {
+    return locale;
+  },
+  /**
+   * Returns the config for all locales, or a single locale by code.
+   * Throws if the requested code is not found.
+   *
+   * @example
+   * Locale.get()       // all locales
+   * Locale.get("fi")   // single locale
+   */
+  get(code) {
+    if (code) {
+      const found = config.locales.find((l) => l.code === code);
+      if (!found) {
+        throw new Error(`${NAME} Locale "${code}" not found.`);
+      }
+      return found;
+    }
+    return config.locales;
+  },
+  // ==========================================================================
+  // Translations
+  // ==========================================================================
+  /**
+   * Binds a locale and returns a translation function for that locale.
+   *
+   * Call once at the top of your page with the current locale, then use
+   * the returned function to look up individual keys.
+   *
+   * Warns if translations are not configured.
+   * Throws if the locale or key is not found.
+   *
+   * @example
+   * const t = Locale.use(locale)
+   * t("nav.home")  // "Home"
+   * t()            // { "nav.home": "Home", ... }
+   */
+  use(locale) {
+    if (!config.translations) {
+      console.warn(
+        `${NAME} Locale.use() was called but translations are not configured. Add a translations path to your i18n config to enable translations.`
+      );
+      return (key) => key ? "" : {};
+    }
+    const record = translations[locale];
+    return (key) => {
+      if (key) {
+        if (!record) {
+          throw new Error(`${NAME} No translations found for locale "${locale}".`);
+        }
+        if (!(key in record)) {
+          throw new Error(`${NAME} Missing translation key "${key}" in ${locale}.json`);
+        }
+        return record[key];
+      }
+      return record ?? {};
+    };
+  },
+  // ==========================================================================
+  // Middleware
+  // ==========================================================================
+  /**
+   * Middleware that redirects requests without a locale prefix to the
+   * correct locale based on the user's cookie.
+   *
+   * Auto-registered when detection is "server" and autoPrefix is enabled.
+   * Can also be used manually via Astro's sequence() helper.
+   *
+   * @example
+   * import { sequence } from "astro/middleware"
+   * import { Locale } from "@mannisto/astro-i18n/runtime"
+   * export const onRequest = sequence(Locale.middleware, myMiddleware)
+   */
+  middleware: defineMiddleware(({ url, cookies, redirect }, next) => {
+    const pathname = url.pathname;
+    const ignoreList = config.routing.autoPrefix !== false ? config.routing.autoPrefix.ignore ?? [] : [];
+    if (ignoreList.some((path) => pathname.startsWith(path))) {
+      return next();
+    }
+    if (pathname === "/") {
+      return next();
+    }
+    const firstSegment = pathname.split("/")[1];
+    if (config.locales.map((l) => l.code).includes(firstSegment)) {
+      return next();
+    }
+    const stored = cookies.get("locale")?.value;
+    const targetLocale = stored && config.locales.map((l) => l.code).includes(stored) ? stored : config.routing.fallback;
+    return redirect(`/${targetLocale}${pathname}`, 302);
+  })
+};
+export {
+  Locale
+};

package/dist/detect/client.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+import { APIRoute } from 'astro';
+declare const prerender = true;
+declare const GET: APIRoute;
+export { GET, prerender };

package/dist/detect/client.js ADDED Viewed

@@ -0,0 +1,30 @@
+// src/detect/client.ts
+import { config } from "virtual:astro-i18n/config";
+var prerender = true;
+var GET = () => {
+  const supported = config.locales.map((l) => l.code);
+  const fallback = config.routing.fallback;
+  const html = `<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+    <script>
+      const supported = ${JSON.stringify(supported)};
+      const fallback = "${fallback}";
+      const stored = localStorage.getItem("locale");
+      const preferred = navigator.language.split("-")[0];
+      const locale = stored ?? (supported.includes(preferred) ? preferred : fallback);
+      localStorage.setItem("locale", locale);
+      window.location.replace("/" + locale + "/");
+    </script>
+  </head>
+  <body></body>
+</html>`;
+  return new Response(html, {
+    headers: { "content-type": "text/html;charset=utf-8" }
+  });
+};
+export {
+  GET,
+  prerender
+};

package/dist/detect/server.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+import { APIRoute } from 'astro';
+declare const prerender = false;
+declare const GET: APIRoute;
+export { GET, prerender };

package/dist/detect/server.js ADDED Viewed

@@ -0,0 +1,21 @@
+import {
+  Locale
+} from "../chunk-SMGDNPQN.js";
+// src/detect/server.ts
+var prerender = false;
+var GET = ({ request, cookies, redirect }) => {
+  const stored = cookies.get("locale")?.value;
+  if (stored && Locale.supported.includes(stored)) {
+    return redirect(`/${stored}/`, 302);
+  }
+  const header = request.headers.get("accept-language") ?? "";
+  const preferred = header.split(",")[0].split(";")[0].split("-")[0].trim().toLowerCase();
+  const locale = Locale.supported.includes(preferred) ? preferred : Locale.fallback;
+  cookies.set("locale", locale, { path: "/" });
+  return redirect(`/${locale}/`, 302);
+};
+export {
+  GET,
+  prerender
+};

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import { AstroIntegration } from 'astro';
+import { I as I18nConfig } from './types-DEfk2GVt.js';
+/**
+ * The @mannisto/astro-i18n Astro integration.
+ *
+ * Adds locale routing, detection, and translations to your Astro project
+ * without relying on Astro's built-in i18n system.
+ *
+ * @example
+ * import i18n from "@mannisto/astro-i18n"
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     i18n({
+ *       locales: [
+ *         { code: "en", name: "English", endonym: "English" },
+ *         { code: "fi", name: "Finnish", endonym: "Suomi", phrase: "Suomeksi" },
+ *       ],
+ *       routing: {
+ *         fallback: "en",
+ *         detection: "server",
+ *         autoPrefix: { ignore: ["/keystatic"] },
+ *       },
+ *       translations: "./src/translations",
+ *     }),
+ *   ],
+ * })
+ */
+declare function i18n(config: I18nConfig): AstroIntegration;
+export { i18n as default };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,185 @@
+// src/lib/validate.ts
+import fs from "fs";
+var NAME = "@mannisto/astro-i18n";
+var Validate = {
+  /**
+   * Validates the user-supplied config object.
+   * Throws a descriptive error if anything is invalid.
+   */
+  config(config) {
+    if (!config.locales || config.locales.length === 0) {
+      throw new Error(`${NAME} No locales defined.`);
+    }
+    for (const locale of config.locales) {
+      if (!locale.code) {
+        throw new Error(`${NAME} A locale is missing a code.`);
+      }
+      if (!locale.name) {
+        throw new Error(`${NAME} Locale "${locale.code}" is missing a name.`);
+      }
+      if (!locale.endonym) {
+        throw new Error(`${NAME} Locale "${locale.code}" is missing an endonym.`);
+      }
+    }
+    if (config.routing?.fallback) {
+      const codes = config.locales.map((l) => l.code);
+      if (!codes.includes(config.routing.fallback)) {
+        throw new Error(
+          `${NAME} Fallback locale "${config.routing.fallback}" not found in locales.`
+        );
+      }
+    }
+    if (config.routing?.autoPrefix && config.routing?.detection !== "server") {
+      throw new Error(`${NAME} autoPrefix is only valid when detection is "server".`);
+    }
+  },
+  /**
+   * Validates that translation files exist for all locales and that all
+   * locales share the same keys as the fallback locale.
+   *
+   * Returns the loaded translation data for use in the virtual module.
+   */
+  translations(config) {
+    const data = {};
+    for (const locale of config.locales) {
+      const filePath = `${config.translations}/${locale.code}.json`;
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`${NAME} Missing translation file: ${filePath}`);
+      }
+      data[locale.code] = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    const fallbackKeys = Object.keys(data[config.routing.fallback]);
+    for (const locale of config.locales) {
+      if (locale.code === config.routing.fallback) continue;
+      const localeKeys = Object.keys(data[locale.code]);
+      for (const key of fallbackKeys) {
+        if (!localeKeys.includes(key)) {
+          throw new Error(`${NAME} Missing translation key "${key}" in ${locale.code}.json`);
+        }
+      }
+    }
+    return data;
+  },
+  /**
+   * Validates that there is no conflicting src/pages/index.astro when
+   * detection is not "none". If one exists it would intercept the injected
+   * detection route at /.
+   */
+  index(root, detection) {
+    if (detection === "none") return;
+    const indexPath = new URL("./src/pages/index.astro", root);
+    if (fs.existsSync(indexPath)) {
+      throw new Error(
+        `${NAME} Found conflicting src/pages/index.astro \u2014 remove it or set routing.detection to "none".`
+      );
+    }
+  }
+};
+// src/index.ts
+var NAME2 = "@mannisto/astro-i18n";
+var DEFAULT_IGNORE = ["/_astro"];
+function resolveConfig(config) {
+  const fallback = config.routing?.fallback ?? config.locales[0].code;
+  const detection = config.routing?.detection ?? "client";
+  const autoPrefix = config.routing?.autoPrefix === false ? false : {
+    ignore: [
+      ...DEFAULT_IGNORE,
+      ...typeof config.routing?.autoPrefix === "object" ? config.routing.autoPrefix.ignore ?? [] : []
+    ]
+  };
+  return {
+    locales: config.locales,
+    routing: { fallback, detection, autoPrefix },
+    // translations are optional — undefined means disabled
+    translations: config.translations
+  };
+}
+function i18n(config) {
+  let resolved;
+  let translationData = {};
+  return {
+    name: NAME2,
+    hooks: {
+      // ======================================================================
+      // astro:config:setup
+      //
+      // Validates config, registers the Vite virtual module plugin, injects
+      // detection routes, and registers the autoPrefix middleware.
+      // ======================================================================
+      "astro:config:setup": ({
+        config: astroConfig,
+        updateConfig,
+        injectRoute,
+        addMiddleware,
+        logger
+      }) => {
+        if (astroConfig.i18n) {
+          logger.warn(
+            "Astro's built-in i18n is configured. Remove the i18n key from astro.config to avoid conflicts."
+          );
+        }
+        Validate.config(config);
+        Validate.index(astroConfig.root, config.routing?.detection ?? "client");
+        resolved = resolveConfig(config);
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "astro-i18n-virtual",
+                resolveId(id) {
+                  if (id === "virtual:astro-i18n/config") {
+                    return "\0virtual:astro-i18n/config";
+                  }
+                },
+                load(id) {
+                  if (id === "\0virtual:astro-i18n/config") {
+                    return `
+export const config = ${JSON.stringify(resolved)}
+export const translations = ${JSON.stringify(translationData)}
+`;
+                  }
+                }
+              }
+            ]
+          }
+        });
+        if (resolved.routing.detection === "server") {
+          injectRoute({
+            pattern: "/",
+            entrypoint: "@mannisto/astro-i18n/detect/server",
+            prerender: false
+          });
+        }
+        if (resolved.routing.detection === "client") {
+          injectRoute({
+            pattern: "/",
+            entrypoint: "@mannisto/astro-i18n/detect/client",
+            prerender: true
+          });
+        }
+        if (resolved.routing.detection === "server" && resolved.routing.autoPrefix !== false) {
+          addMiddleware({
+            entrypoint: "@mannisto/astro-i18n/middleware",
+            order: "pre"
+          });
+        }
+        logger.info("i18n configured.");
+      },
+      // ======================================================================
+      // astro:config:done
+      //
+      // Validates and loads translation files only if translations are
+      // configured. Runs after all integrations have finished setup.
+      // ======================================================================
+      "astro:config:done": () => {
+        if (resolved.translations) {
+          translationData = Validate.translations(resolved);
+        }
+      }
+    }
+  };
+}
+export {
+  i18n as default
+};

package/dist/middleware.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+import * as astro from 'astro';
+declare const onRequest: astro.MiddlewareHandler;
+export { onRequest };

package/dist/middleware.js ADDED Viewed

@@ -0,0 +1,9 @@
+import {
+  Locale
+} from "./chunk-SMGDNPQN.js";
+// src/middleware.ts
+var onRequest = Locale.middleware;
+export {
+  onRequest
+};

package/dist/runtime.d.ts ADDED Viewed

@@ -0,0 +1,67 @@
+import * as astro from 'astro';
+import { L as LocaleCode, a as LocaleConfig } from './types-DEfk2GVt.js';
+/**
+ * Primary public API for locale access, translations, and middleware.
+ *
+ * Always import from the runtime subpath in pages and components:
+ * @example
+ * import { Locale } from "@mannisto/astro-i18n/runtime"
+ */
+declare const Locale: {
+    /**
+     * All supported locale codes.
+     * @example ["en", "fi"]
+     */
+    readonly supported: LocaleCode[];
+    /**
+     * The fallback locale code.
+     * @example "en"
+     */
+    readonly fallback: LocaleCode;
+    /**
+     * Returns the current locale from Astro.params.
+     * @example
+     * const locale = Locale.current(Astro.params.locale)
+     */
+    current(locale: string): LocaleCode;
+    /**
+     * Returns the config for all locales, or a single locale by code.
+     * Throws if the requested code is not found.
+     *
+     * @example
+     * Locale.get()       // all locales
+     * Locale.get("fi")   // single locale
+     */
+    get(code?: LocaleCode): LocaleConfig | LocaleConfig[];
+    /**
+     * Binds a locale and returns a translation function for that locale.
+     *
+     * Call once at the top of your page with the current locale, then use
+     * the returned function to look up individual keys.
+     *
+     * Warns if translations are not configured.
+     * Throws if the locale or key is not found.
+     *
+     * @example
+     * const t = Locale.use(locale)
+     * t("nav.home")  // "Home"
+     * t()            // { "nav.home": "Home", ... }
+     */
+    use(locale: LocaleCode): (key?: string) => string | Record<string, string>;
+    /**
+     * Middleware that redirects requests without a locale prefix to the
+     * correct locale based on the user's cookie.
+     *
+     * Auto-registered when detection is "server" and autoPrefix is enabled.
+     * Can also be used manually via Astro's sequence() helper.
+     *
+     * @example
+     * import { sequence } from "astro/middleware"
+     * import { Locale } from "@mannisto/astro-i18n/runtime"
+     * export const onRequest = sequence(Locale.middleware, myMiddleware)
+     */
+    middleware: astro.MiddlewareHandler;
+};
+export { Locale };

package/dist/runtime.js ADDED Viewed

@@ -0,0 +1,6 @@
+import {
+  Locale
+} from "./chunk-SMGDNPQN.js";
+export {
+  Locale
+};

package/dist/types-DEfk2GVt.d.ts ADDED Viewed

@@ -0,0 +1,74 @@
+/** A locale code, e.g. "en", "fi", "fr" */
+type LocaleCode = string;
+/** Configuration for a single locale */
+type LocaleConfig = {
+    /** The locale code, e.g. "en" */
+    code: LocaleCode;
+    /** The locale name in English, e.g. "English" */
+    name: string;
+    /** The locale name in its own language, e.g. "Suomi" */
+    endonym: string;
+    /** Optional short phrase for locale switchers, e.g. "Suomeksi" */
+    phrase?: string;
+};
+/**
+ * How the user's preferred locale is detected on their first visit.
+ *
+ * - "server" — reads the Accept-Language header via a server-side API route
+ * - "client" — reads navigator.language via a static JS redirect page
+ * - "none"   — no detection, user must navigate to a locale URL directly
+ */
+type DetectionMode = "server" | "client" | "none";
+/**
+ * Configuration for the autoPrefix middleware.
+ * Only valid when detection is "server".
+ */
+type AutoPrefixConfig = {
+    /**
+     * URL path prefixes that should bypass the autoPrefix middleware.
+     * Useful for CMS admin routes, API routes, etc.
+     *
+     * @example ["/keystatic", "/api"]
+     */
+    ignore?: string[];
+};
+/** User-supplied routing configuration */
+type RoutingConfig = {
+    /**
+     * The locale code to fall back to when no match is found.
+     * Defaults to the first locale in the locales array.
+     */
+    fallback?: LocaleCode;
+    /**
+     * How the user's preferred locale is detected on first visit.
+     * @default "client"
+     */
+    detection?: DetectionMode;
+    /**
+     * When enabled, the middleware automatically prefixes unknown routes
+     * with the user's preferred locale. Only valid when detection is "server".
+     *
+     * Set to false to disable entirely, or pass an object to configure
+     * which paths should be ignored.
+     *
+     * @default { ignore: ["/_astro"] }
+     */
+    autoPrefix?: boolean | AutoPrefixConfig;
+};
+/** The configuration object passed to the i18n() integration */
+type I18nConfig = {
+    /** The list of supported locales, in order of preference */
+    locales: LocaleConfig[];
+    /** Routing and detection options */
+    routing?: RoutingConfig;
+    /**
+     * Path to the translations directory, relative to the project root.
+     * Each locale should have a corresponding JSON file, e.g. en.json, fi.json.
+     * If not set, translations are disabled and Locale.t() will warn when called.
+     *
+     * @example "./src/translations"
+     */
+    translations?: string;
+};
+export type { I18nConfig as I, LocaleCode as L, LocaleConfig as a };

package/package.json ADDED Viewed

@@ -0,0 +1,87 @@
+{
+  "name": "@mannisto/astro-i18n",
+  "version": "1.0.0-alpha.1",
+  "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",
+  "homepage": "https://github.com/eremannisto/astro-i18n#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eremannisto/astro-i18n"
+  },
+  "bugs": {
+    "url": "https://github.com/eremannisto/astro-i18n/issues"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "i18n",
+    "internationalisation",
+    "routing",
+    "translations"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "default": "./dist/middleware.js"
+    },
+    "./detect/server": {
+      "types": "./dist/detect/server.d.ts",
+      "default": "./dist/detect/server.js"
+    },
+    "./detect/client": {
+      "types": "./dist/detect/client.d.ts",
+      "default": "./dist/detect/client.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "runtime": [
+        "./dist/runtime.d.ts"
+      ],
+      "middleware": [
+        "./dist/middleware.d.ts"
+      ],
+      "detect/server": [
+        "./dist/detect/server.d.ts"
+      ],
+      "detect/client": [
+        "./dist/detect/client.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@playwright/test": "^1.50.0",
+    "@types/node": "^22.0.0",
+    "astro": "^5.17.3",
+    "prettier": "^3.8.1",
+    "prettier-plugin-astro": "^0.14.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "format": "prettier --write .",
+    "lint": "biome lint",
+    "check": "biome check",
+    "test:unit": "vitest run",
+    "test:e2e": "pnpm build > /dev/null 2>&1 && playwright test",
+    "test": "pnpm run test:unit && pnpm run test:e2e"
+  }
+}