@zachhandley/ez-i18n 0.3.4 → 0.3.5

package/README.md

@@ -76,6 +76,75 @@ t('common.countdown', { seconds: 5 }); // "Ready in 5 seconds"
 await setLocale('es');
 ```
 
+## Virtual Modules
+
+### `ez-i18n:runtime`
+
+Core translation functions:
+
+```ts
+import { t, locale, setLocale, initLocale } from 'ez-i18n:runtime';
+
+t('key');                    // Translate a key
+t('key', { name: 'World' }); // With interpolation
+locale;                      // Reactive store with current locale
+await setLocale('es');       // Change locale (persists to cookie)
+initLocale('en', data);      // Initialize with translations
+```
+
+### `ez-i18n:config`
+
+Access your i18n configuration:
+
+```ts
+import {
+  locales,          // ['en', 'es', 'fr']
+  defaultLocale,    // 'en'
+  cookieName,       // 'ez-locale'
+  localeNames,      // { en: 'English', es: 'Español', fr: 'Français' }
+  localeToBCP47,    // { en: 'en-US', es: 'es-ES', fr: 'fr-FR' }
+  localeDirections, // { en: 'ltr', es: 'ltr', ar: 'rtl' }
+} from 'ez-i18n:config';
+```
+
+### `ez-i18n:translations`
+
+Dynamic translation loading:
+
+```ts
+import { loadTranslations, translationLoaders } from 'ez-i18n:translations';
+
+const data = await loadTranslations('es');
+```
+
+## Locale Utilities
+
+The package includes a comprehensive locale database with 100+ languages:
+
+```ts
+import {
+  LOCALE_DATABASE,
+  getLocaleInfo,
+  buildLocaleNames,
+  buildLocaleToBCP47,
+  buildLocaleDirections,
+} from '@zachhandley/ez-i18n';
+import type { LocaleInfo } from '@zachhandley/ez-i18n';
+
+// Get info for any locale
+const info = getLocaleInfo('es');
+// { name: 'Español', englishName: 'Spanish', bcp47: 'es-ES', dir: 'ltr' }
+
+// Build mappings for your supported locales
+const names = buildLocaleNames(['en', 'es', 'ar']);
+// { en: 'English', es: 'Español', ar: 'العربية' }
+
+const directions = buildLocaleDirections(['en', 'es', 'ar']);
+// { en: 'ltr', es: 'ltr', ar: 'rtl' }
+```
+
+Includes native display names, English names, BCP47 codes, and text direction (LTR/RTL) for all major languages and regional variants.
+
 ## Framework Bindings
 
 - React: `@zachhandley/ez-i18n-react`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachhandley/ez-i18n",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "publishConfig": {
     "access": "public"
   },
@@ -30,7 +30,7 @@
   },
   "files": [
     "dist",
-    "src",
+    "src/components",
     "README.md"
   ],
   "keywords": [

package/src/index.ts

@@ -1,130 +0,0 @@
-import type { AstroIntegration, HookParameters } from 'astro';
-import type { EzI18nConfig } from './types';
-import { vitePlugin, resolveConfig } from './vite-plugin';
-
-export type { EzI18nConfig, TranslateFunction } from './types';
-export { LOCALE_DATABASE, getLocaleInfo, buildLocaleNames, buildLocaleToBCP47, buildLocaleDirections } from './utils/locales';
-export type { LocaleInfo } from './utils/locales';
-
-/**
- * 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;
-  /** Display names for each locale (in native language) */
-  export const localeNames: Record<string, string>;
-  /** BCP47 language tags for each locale */
-  export const localeToBCP47: Record<string, string>;
-  /** Text direction for each locale ('ltr' or 'rtl') */
-  export const localeDirections: Record<string, 'ltr' | 'rtl'>;
-}
-
-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

@@ -1,82 +0,0 @@
-import { defineMiddleware } from 'astro:middleware';
-import type { TranslateFunction } from './types';
-
-/**
- * Create a server-side translation function for the given translations object
- */
-function createT(translations: Record<string, unknown>): TranslateFunction {
-  return (key: string, params?: Record<string, string | number>): string => {
-    const keys = key.split('.');
-    let value: unknown = translations;
-    for (const k of keys) {
-      if (value == null || typeof value !== 'object') return key;
-      value = (value as Record<string, unknown>)[k];
-    }
-    if (typeof value !== 'string') return key;
-    if (!params) return value;
-    return value.replace(/\{(\w+)\}/g, (_, p) => String(params[p] ?? `{${p}}`));
-  };
-}
-
-/**
- * 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 = {};
-  }
-
-  // Create server-side translation function
-  locals.t = createT(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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,122 +0,0 @@
-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();
-}

package/src/types.ts

@@ -1,125 +0,0 @@
-/**
- * Translation path for a single locale:
- * - Single file: `./src/i18n/en.json`
- * - Folder: `./src/i18n/en/` (auto-discover all JSONs inside)
- * - Glob: `./src/i18n/en/**.json` (recursive)
- * - Array: `['./common.json', './auth.json']`
- */
-export type LocaleTranslationPath = string | string[];
-
-/**
- * Translation config can be:
- * - A base directory string (auto-discovers locale folders): './public/i18n/'
- * - Per-locale mapping: { en: './src/i18n/en/', es: './src/i18n/es.json' }
- */
-export type TranslationsConfig = string | Record<string, LocaleTranslationPath>;
-
-/**
- * Configuration for ez-i18n Astro integration
- */
-export interface EzI18nConfig {
-  /**
-   * List of supported locale codes (e.g., ['en', 'es', 'fr'])
-   * Optional if using directory-based auto-discovery - locales will be
-   * detected from folder names in the translations directory.
-   */
-  locales?: string[];
-
-  /**
-   * Default locale to use when no preference is detected.
-   * Required - this tells us what to fall back to.
-   */
-  defaultLocale: string;
-
-  /**
-   * Cookie name for storing locale preference
-   * @default 'ez-locale'
-   */
-  cookieName?: string;
-
-  /**
-   * Translation file paths configuration.
-   * Paths are relative to your project root.
-   *
-   * Can be:
-   * - A base directory (auto-discovers locale folders):
-   *   translations: './public/i18n/'
-   *   → Scans for en/, es/, fr/ folders and their JSON files
-   *   → Auto-populates `locales` from discovered folders
-   *
-   * - Per-locale mapping with flexible path types:
-   *   translations: {
-   *     en: './src/i18n/en.json',           // single file
-   *     es: './src/i18n/es/',               // folder (all JSONs)
-   *     fr: './src/i18n/fr/**.json',          // glob pattern
-   *     de: ['./common.json', './auth.json'] // array of files
-   *   }
-   *
-   * If not specified, auto-discovers from ./public/i18n/
-   */
-  translations?: TranslationsConfig;
-
-  /**
-   * Derive namespace from file path relative to locale folder.
-   *
-   * When enabled:
-   * - `en/auth/login.json` with `{ "title": "..." }` → `$t('auth.login.title')`
-   * - `en/common.json` with `{ "actions": {...} }` → `$t('common.actions.save')`
-   *
-   * The file path (minus locale folder and .json extension) becomes the key prefix.
-   *
-   * @default true when using folder-based translations config
-   */
-  pathBasedNamespacing?: boolean;
-}
-
-/**
- * Resolved config with defaults applied.
- * After resolution:
- * - locales is always populated (from config or auto-discovered)
- * - translations is normalized to arrays of absolute file paths
- */
-export interface ResolvedEzI18nConfig {
-  locales: string[];
-  defaultLocale: string;
-  cookieName: string;
-  /** Normalized: locale → array of resolved absolute file paths */
-  translations: Record<string, string[]>;
-  /** Whether to derive namespace from file path */
-  pathBasedNamespacing: boolean;
-  /** Base directory for each locale (used for namespace calculation) */
-  localeBaseDirs: Record<string, string>;
-}
-
-/**
- * Cache file structure (.ez-i18n.json)
- * Used to speed up subsequent builds by caching discovered translations
- */
-export interface TranslationCache {
-  version: number;
-  /** Discovered locale → file paths mapping */
-  discovered: Record<string, string[]>;
-  /** ISO timestamp of last scan */
-  lastScan: string;
-}
-
-/**
- * Translation function type
- */
-export 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>;
-      /** Server-side translation function */
-      t: TranslateFunction;
-    }
-  }
-}

package/src/utils/index.ts

@@ -1,16 +0,0 @@
-export {
-  detectPathType,
-  resolveTranslationPaths,
-  autoDiscoverTranslations,
-  resolveTranslationsConfig,
-  deepMerge,
-  loadCache,
-  saveCache,
-  isCacheValid,
-  toRelativeImport,
-  toGlobPattern,
-  getNamespaceFromPath,
-  wrapWithNamespace,
-  generateNamespaceWrapperCode,
-  type PathType,
-} from './translations';