@zachhandley/ez-i18n 0.1.0

package/dist/runtime/vue-plugin.js

@@ -0,0 +1,110 @@
+// src/runtime/vue-plugin.ts
+import { computed as computed2 } from "vue";
+import { useStore } from "@nanostores/vue";
+
+// src/runtime/store.ts
+import { atom, computed } from "nanostores";
+import { persistentAtom } from "@nanostores/persistent";
+var serverLocale = atom(null);
+var localePreference = persistentAtom("ez-locale", "en", {
+  encode: (value) => value,
+  decode: (value) => value
+});
+var effectiveLocale = computed(
+  [serverLocale, localePreference],
+  (server, client) => server ?? client
+);
+var translations = atom({});
+var localeLoading = atom(false);
+async function setLocale(locale, options = {}) {
+  const opts = typeof options === "string" ? { cookieName: options } : options;
+  const { cookieName = "ez-locale", loadTranslations } = opts;
+  localeLoading.set(true);
+  try {
+    if (loadTranslations) {
+      const mod = await loadTranslations();
+      const trans = "default" in mod ? mod.default : mod;
+      translations.set(trans);
+    }
+    localePreference.set(locale);
+    serverLocale.set(locale);
+    if (typeof document !== "undefined") {
+      document.cookie = `${cookieName}=${locale}; path=/; max-age=31536000; samesite=lax`;
+    }
+    if (typeof document !== "undefined") {
+      document.dispatchEvent(
+        new CustomEvent("ez-i18n:locale-changed", {
+          detail: { locale },
+          bubbles: true
+        })
+      );
+    }
+  } finally {
+    localeLoading.set(false);
+  }
+}
+
+// src/runtime/vue-plugin.ts
+function getNestedValue(obj, path) {
+  const keys = path.split(".");
+  let value = obj;
+  for (const key of keys) {
+    if (value == null || typeof value !== "object") {
+      return void 0;
+    }
+    value = value[key];
+  }
+  return value;
+}
+function interpolate(str, params) {
+  if (!params) return str;
+  return str.replace(/\{(\w+)\}/g, (match, key) => {
+    return key in params ? String(params[key]) : match;
+  });
+}
+function createTranslateFunction(translationsRef) {
+  return (key, params) => {
+    const trans = translationsRef.value;
+    const value = getNestedValue(trans, key);
+    if (typeof value !== "string") {
+      if (import.meta.env?.DEV) {
+        console.warn("[ez-i18n] Missing translation:", key);
+      }
+      return key;
+    }
+    return interpolate(value, params);
+  };
+}
+var ezI18nVue = {
+  install(app) {
+    const locale = useStore(effectiveLocale);
+    const trans = useStore(translations);
+    const transComputed = computed2(() => trans.value);
+    const t = createTranslateFunction(transComputed);
+    app.config.globalProperties.$t = t;
+    app.config.globalProperties.$locale = locale;
+    app.config.globalProperties.$setLocale = setLocale;
+    app.provide("ez-i18n", {
+      t,
+      locale,
+      setLocale
+    });
+  }
+};
+function useI18n() {
+  const locale = useStore(effectiveLocale);
+  const trans = useStore(translations);
+  const transComputed = computed2(() => trans.value);
+  const t = createTranslateFunction(transComputed);
+  return {
+    t,
+    locale,
+    setLocale
+  };
+}
+var vue_plugin_default = ezI18nVue;
+export {
+  vue_plugin_default as default,
+  ezI18nVue,
+  useI18n
+};

package/dist/types-DwCG8sp8.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Configuration for ez-i18n Astro integration
+ */
+interface EzI18nConfig {
+    /**
+     * List of supported locale codes (e.g., ['en', 'es', 'fr'])
+     */
+    locales: string[];
+    /**
+     * Default locale to use when no preference is detected
+     */
+    defaultLocale: string;
+    /**
+     * Cookie name for storing locale preference
+     * @default 'ez-locale'
+     */
+    cookieName?: string;
+    /**
+     * Translation file paths for each locale.
+     * Paths are relative to your project root.
+     * Dynamic imports will be generated for code splitting.
+     * @example
+     * translations: {
+     *   en: './src/i18n/en.json',
+     *   es: './src/i18n/es.json',
+     * }
+     */
+    translations?: Record<string, string>;
+}
+/**
+ * Translation function type
+ */
+type TranslateFunction = (key: string, params?: Record<string, string | number>) => string;
+/**
+ * Augment Astro's locals type
+ */
+declare global {
+    namespace App {
+        interface Locals {
+            /** Current locale code */
+            locale: string;
+            /** Loaded translations for the current locale */
+            translations: Record<string, unknown>;
+        }
+    }
+}
+
+export type { EzI18nConfig as E, TranslateFunction as T };

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@zachhandley/ez-i18n",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Cookie-based i18n for Astro + Vue. No URL prefixes, reactive language switching.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vue": {
+      "types": "./dist/runtime/vue-plugin.d.ts",
+      "import": "./dist/runtime/vue-plugin.js"
+    },
+    "./middleware": {
+      "import": "./dist/middleware.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./astro": {
+      "import": "./src/components/EzI18nHead.astro"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build",
+    "release": "pnpm build && npm publish",
+    "release:dry": "pnpm build && npm publish --dry-run"
+  },
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "i18n",
+    "internationalization",
+    "vue",
+    "cookie-based",
+    "no-url-prefix"
+  ],
+  "author": "Zach Handley <zachhandley@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/zachhandley/ez-i18n#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zachhandley/ez-i18n.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zachhandley/ez-i18n/issues"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0",
+    "vue": "^3.4.0",
+    "nanostores": "^0.9.0 || ^0.10.0 || ^0.11.0",
+    "@nanostores/persistent": "^0.10.0",
+    "@nanostores/vue": "^0.10.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "@nanostores/vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "astro": "^5.1.1",
+    "nanostores": "^0.11.3",
+    "@nanostores/persistent": "^0.10.2",
+    "@nanostores/vue": "^0.10.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vue": "^3.5.13",
+    "vite": "^6.0.3"
+  },
+  "packageManager": "pnpm@10.17.1+sha512.17c560fca4867ae9473a3899ad84a88334914f379be46d455cbf92e5cf4b39d34985d452d2583baf19967fa76cb5c17bc9e245529d0b98745721aa7200ecaf7a"
+}

package/src/components/EzI18nHead.astro

@@ -0,0 +1,62 @@
+---
+/**
+ * EzI18nHead - Astro component for i18n hydration setup
+ *
+ * Place this in your layout's <head> to properly initialize
+ * the i18n runtime with server-side loaded translations.
+ *
+ * @example
+ * ---
+ * import { EzI18nHead } from '@zachhandley/ez-i18n/astro';
+ * const { locale, translations } = Astro.locals;
+ * ---
+ * <html lang={locale}>
+ *   <head>
+ *     <EzI18nHead locale={locale} translations={translations} />
+ *   </head>
+ *   <body><slot /></body>
+ * </html>
+ */
+interface Props {
+  /** Current locale code from Astro.locals.locale */
+  locale: string;
+  /** Translations object from Astro.locals.translations */
+  translations: Record<string, unknown>;
+}
+
+const { locale, translations } = Astro.props;
+
+// Serialize translations for inline script
+const serializedTranslations = JSON.stringify(translations);
+---
+
+<script
+  is:inline
+  data-ez-i18n-locale={locale}
+  data-ez-i18n-translations={serializedTranslations}
+>
+  // Initialize ez-i18n runtime with server-provided values
+  (function() {
+    const script = document.currentScript;
+    if (!script) return;
+
+    const locale = script.dataset.ezI18nLocale;
+    const translations = JSON.parse(script.dataset.ezI18nTranslations || '{}');
+
+    // Store for runtime initialization
+    window.__EZ_I18N_INIT__ = { locale, translations };
+  })();
+</script>
+
+<script>
+  // Import and initialize the runtime stores
+  import { initLocale, setTranslations } from '@zachhandley/ez-i18n/runtime';
+
+  // Get initialization data from inline script
+  const initData = (window as any).__EZ_I18N_INIT__;
+  if (initData) {
+    initLocale(initData.locale, initData.translations);
+    setTranslations(initData.translations);
+    delete (window as any).__EZ_I18N_INIT__;
+  }
+</script>

package/src/index.ts

@@ -0,0 +1,122 @@
+import type { AstroIntegration, HookParameters } from 'astro';
+import type { EzI18nConfig } from './types';
+import { vitePlugin, resolveConfig } from './vite-plugin';
+
+export type { EzI18nConfig, TranslateFunction } from './types';
+
+/**
+ * ez-i18n Astro integration
+ *
+ * Provides cookie-based i18n without URL prefixes.
+ *
+ * @example
+ * // astro.config.ts
+ * import ezI18n from '@zachhandley/ez-i18n';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     ezI18n({
+ *       locales: ['en', 'es', 'fr'],
+ *       defaultLocale: 'en',
+ *       translations: {
+ *         en: './src/i18n/en.json',
+ *         es: './src/i18n/es.json',
+ *       },
+ *     }),
+ *   ],
+ * });
+ */
+export default function ezI18n(config: EzI18nConfig): AstroIntegration {
+  const resolved = resolveConfig(config);
+
+  return {
+    name: 'ez-i18n',
+    hooks: {
+      'astro:config:setup': ({
+        updateConfig,
+        addMiddleware,
+        injectScript,
+      }: HookParameters<'astro:config:setup'>) => {
+        // Add Vite plugin for virtual modules
+        updateConfig({
+          vite: {
+            plugins: [vitePlugin(config)],
+          },
+        });
+
+        // Add locale detection middleware
+        addMiddleware({
+          entrypoint: '@zachhandley/ez-i18n/middleware',
+          order: 'pre',
+        });
+
+        // Inject hydration script to sync localStorage with cookie
+        // This prevents hydration mismatch when server and client disagree
+        const hydrationScript = `
+(function() {
+  try {
+    var cookieName = ${JSON.stringify(resolved.cookieName)};
+    var stored = localStorage.getItem(cookieName);
+    var cookieMatch = document.cookie.match(new RegExp(cookieName + '=([^;]+)'));
+    var cookie = cookieMatch ? cookieMatch[1] : null;
+    if (cookie && stored !== cookie) {
+      localStorage.setItem(cookieName, cookie);
+    }
+  } catch (e) {}
+})();
+`;
+        injectScript('head-inline', hydrationScript);
+      },
+
+      'astro:config:done': ({
+        injectTypes,
+      }: HookParameters<'astro:config:done'>) => {
+        // Inject type declarations for virtual modules
+        injectTypes({
+          filename: 'virtual.d.ts',
+          content: `\
+declare module 'ez-i18n:config' {
+  /** List of all supported locale codes */
+  export const locales: readonly string[];
+  /** Default locale when no preference is detected */
+  export const defaultLocale: string;
+  /** Cookie name used to store locale preference */
+  export const cookieName: string;
+}
+
+declare module 'ez-i18n:runtime' {
+  import type { ReadableAtom } from 'nanostores';
+  /** Reactive store containing the current locale */
+  export const locale: ReadableAtom<string>;
+  /**
+   * Translate a key to the current locale
+   * @param key - Dot-notation key (e.g., 'common.welcome')
+   * @param params - Optional interpolation params for {placeholder} syntax
+   */
+  export function t(key: string, params?: Record<string, string | number>): string;
+  /**
+   * Set the current locale and persist to cookie/localStorage
+   * @param locale - Locale code to switch to
+   * @param cookieName - Optional custom cookie name
+   */
+  export function setLocale(locale: string, cookieName?: string): Promise<void>;
+  /**
+   * Initialize the locale store with translations
+   * @param locale - Initial locale code
+   * @param translations - Optional initial translations object
+   */
+  export function initLocale(locale: string, translations?: Record<string, unknown>): void;
+}
+
+declare module 'ez-i18n:translations' {
+  /** Load translations for a specific locale */
+  export function loadTranslations(locale: string): Promise<Record<string, unknown>>;
+  /** Get the translation loader map from config */
+  export const translationLoaders: Record<string, () => Promise<{ default: Record<string, unknown> }>>;
+}
+`,
+        });
+      },
+    },
+  };
+}

package/src/middleware.ts

@@ -0,0 +1,61 @@
+import { defineMiddleware } from 'astro:middleware';
+
+/**
+ * Locale detection middleware for ez-i18n
+ *
+ * Detection priority:
+ * 1. ?lang query parameter (allows explicit switching)
+ * 2. Cookie value
+ * 3. Accept-Language header
+ * 4. Default locale
+ */
+export const onRequest = defineMiddleware(async ({ cookies, request, locals }, next) => {
+  // Import config from virtual module (provided by vite-plugin)
+  const { locales, defaultLocale, cookieName } = await import('ez-i18n:config');
+
+  const url = new URL(request.url);
+
+  // Priority 1: Query parameter
+  const langParam = url.searchParams.get('lang');
+
+  // Priority 2: Cookie
+  const cookieValue = cookies.get(cookieName)?.value;
+
+  // Priority 3: Accept-Language header
+  const acceptLang = request.headers.get('accept-language');
+  const browserLang = acceptLang?.split(',')[0]?.split('-')[0];
+
+  // Determine locale with priority
+  let locale = defaultLocale;
+
+  if (langParam && locales.includes(langParam)) {
+    locale = langParam;
+  } else if (cookieValue && locales.includes(cookieValue)) {
+    locale = cookieValue;
+  } else if (browserLang && locales.includes(browserLang)) {
+    locale = browserLang;
+  }
+
+  // Set locale on locals for use in pages
+  locals.locale = locale;
+
+  // Load translations for the current locale
+  try {
+    const { loadTranslations } = await import('ez-i18n:translations');
+    locals.translations = await loadTranslations(locale);
+  } catch {
+    // Fallback to empty translations if loader not configured
+    locals.translations = {};
+  }
+
+  // Update cookie if changed via query param
+  if (langParam && langParam !== cookieValue && locales.includes(langParam)) {
+    cookies.set(cookieName, locale, {
+      path: '/',
+      maxAge: 60 * 60 * 24 * 365, // 1 year
+      sameSite: 'lax',
+    });
+  }
+
+  return next();
+});

package/src/runtime/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime exports for ez-i18n
+ *
+ * This module is imported by the ez-i18n:runtime virtual module
+ * and can also be used directly in Vue components
+ */
+export {
+  effectiveLocale,
+  translations,
+  localePreference,
+  localeLoading,
+  initLocale,
+  setLocale,
+  setTranslations,
+  getLocale,
+  getTranslations,
+} from './store';
+
+export type { TranslationLoader } from './store';

package/src/runtime/store.ts

@@ -0,0 +1,122 @@
+import { atom, computed } from 'nanostores';
+import { persistentAtom } from '@nanostores/persistent';
+
+/**
+ * Server-provided locale (set during SSR/hydration)
+ * Takes precedence over client preference to prevent hydration mismatch
+ */
+const serverLocale = atom<string | null>(null);
+
+/**
+ * Client-side locale preference (persisted to localStorage)
+ */
+export const localePreference = persistentAtom<string>('ez-locale', 'en', {
+  encode: (value) => value,
+  decode: (value) => value,
+});
+
+/**
+ * Effective locale - uses server locale if set, otherwise client preference
+ */
+export const effectiveLocale = computed(
+  [serverLocale, localePreference],
+  (server, client) => server ?? client
+);
+
+/**
+ * Current translations object (reactive)
+ */
+export const translations = atom<Record<string, unknown>>({});
+
+/**
+ * Whether locale is currently being changed
+ */
+export const localeLoading = atom<boolean>(false);
+
+/**
+ * Initialize locale from server-provided value
+ * Called during hydration to sync server and client state
+ */
+export function initLocale(locale: string, trans?: Record<string, unknown>): void {
+  serverLocale.set(locale);
+  localePreference.set(locale);
+  if (trans) {
+    translations.set(trans);
+  }
+}
+
+/**
+ * Set the translations object
+ */
+export function setTranslations(trans: Record<string, unknown>): void {
+  translations.set(trans);
+}
+
+/** Type for translation loader function */
+export type TranslationLoader = () => Promise<{ default?: Record<string, unknown> } | Record<string, unknown>>;
+
+/**
+ * Change locale and update cookie
+ * Optionally loads new translations dynamically
+ * @param locale - New locale code
+ * @param options - Options object or cookie name for backwards compatibility
+ */
+export async function setLocale(
+  locale: string,
+  options: string | {
+    cookieName?: string;
+    loadTranslations?: TranslationLoader;
+  } = {}
+): Promise<void> {
+  // Handle backwards compatibility with string cookieName
+  const opts = typeof options === 'string'
+    ? { cookieName: options }
+    : options;
+  const { cookieName = 'ez-locale', loadTranslations } = opts;
+
+  localeLoading.set(true);
+
+  try {
+    // Load new translations if loader provided
+    if (loadTranslations) {
+      const mod = await loadTranslations();
+      const trans = 'default' in mod ? mod.default : mod;
+      translations.set(trans as Record<string, unknown>);
+    }
+
+    // Update stores
+    localePreference.set(locale);
+    serverLocale.set(locale);
+
+    // Update cookie
+    if (typeof document !== 'undefined') {
+      document.cookie = `${cookieName}=${locale}; path=/; max-age=31536000; samesite=lax`;
+    }
+
+    // Dispatch event for components that need to react
+    if (typeof document !== 'undefined') {
+      document.dispatchEvent(
+        new CustomEvent('ez-i18n:locale-changed', {
+          detail: { locale },
+          bubbles: true,
+        })
+      );
+    }
+  } finally {
+    localeLoading.set(false);
+  }
+}
+
+/**
+ * Get current locale value (non-reactive)
+ */
+export function getLocale(): string {
+  return effectiveLocale.get();
+}
+
+/**
+ * Get current translations (non-reactive)
+ */
+export function getTranslations(): Record<string, unknown> {
+  return translations.get();
+}