@zachhandley/ez-i18n 0.2.2 → 0.3.0

package/src/runtime/store.ts

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

package/src/utils/index.ts

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