@zachhandley/ez-i18n 0.1.0

package/src/runtime/vue-plugin.ts

@@ -0,0 +1,137 @@
+import type { App, Plugin, ComputedRef } from 'vue';
+import { computed } from 'vue';
+import { useStore } from '@nanostores/vue';
+import { effectiveLocale, translations, setLocale } from './store';
+import type { TranslateFunction } from '../types';
+
+/**
+ * Get nested value from object using dot notation
+ */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const keys = path.split('.');
+  let value: unknown = obj;
+
+  for (const key of keys) {
+    if (value == null || typeof value !== 'object') {
+      return undefined;
+    }
+    value = (value as Record<string, unknown>)[key];
+  }
+
+  return value;
+}
+
+/**
+ * Interpolate params into string
+ */
+function interpolate(
+  str: string,
+  params?: Record<string, string | number>
+): string {
+  if (!params) return str;
+  return str.replace(/\{(\w+)\}/g, (match, key) => {
+    return key in params ? String(params[key]) : match;
+  });
+}
+
+/**
+ * Create a translation function bound to a translations object
+ */
+function createTranslateFunction(
+  translationsRef: ComputedRef<Record<string, unknown>>
+): TranslateFunction {
+  return (key: string, params?: Record<string, string | number>): string => {
+    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);
+  };
+}
+
+/**
+ * Vue plugin that provides global $t(), $locale, and $setLocale
+ *
+ * @example
+ * // In _vueEntrypoint.ts or main.ts
+ * import { ezI18nVue } from 'ez-i18n/vue';
+ *
+ * export default (app) => {
+ *   app.use(ezI18nVue);
+ * };
+ *
+ * @example
+ * // In Vue components
+ * <template>
+ *   <h1>{{ $t('welcome.title') }}</h1>
+ *   <p>{{ $t('welcome.message', { name: userName }) }}</p>
+ *   <button @click="$setLocale('es')">Español</button>
+ * </template>
+ */
+export const ezI18nVue: Plugin = {
+  install(app: App) {
+    // Get reactive store values
+    const locale = useStore(effectiveLocale);
+    const trans = useStore(translations);
+
+    // Create reactive computed for translations
+    const transComputed = computed(() => trans.value);
+
+    // Create translate function
+    const t = createTranslateFunction(transComputed);
+
+    // Add global properties
+    app.config.globalProperties.$t = t;
+    app.config.globalProperties.$locale = locale;
+    app.config.globalProperties.$setLocale = setLocale;
+
+    // Also provide for composition API usage
+    app.provide('ez-i18n', {
+      t,
+      locale,
+      setLocale,
+    });
+  },
+};
+
+/**
+ * Composable for using i18n in Vue components with Composition API
+ *
+ * @example
+ * <script setup>
+ * import { useI18n } from 'ez-i18n/vue';
+ *
+ * const { t, locale, setLocale } = useI18n();
+ * const greeting = t('welcome.greeting');
+ * </script>
+ */
+export function useI18n() {
+  const locale = useStore(effectiveLocale);
+  const trans = useStore(translations);
+  const transComputed = computed(() => trans.value);
+  const t = createTranslateFunction(transComputed);
+
+  return {
+    t,
+    locale,
+    setLocale,
+  };
+}
+
+// Type augmentation for Vue global properties
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $t: TranslateFunction;
+    /** Current locale (reactive ref from nanostore) */
+    $locale: Readonly<import('vue').Ref<string>>;
+    $setLocale: typeof setLocale;
+  }
+}
+
+export default ezI18nVue;

package/src/types.ts

@@ -0,0 +1,61 @@
+/**
+ * Configuration for ez-i18n Astro integration
+ */
+export 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>;
+}
+
+/**
+ * Resolved config with defaults applied
+ */
+export interface ResolvedEzI18nConfig {
+  locales: string[];
+  defaultLocale: string;
+  cookieName: string;
+  translations: Record<string, 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/virtual.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Type declarations for ez-i18n virtual modules
+ *
+ * Note: These are also injected via injectTypes() for consumer projects.
+ * This file provides types during package development.
+ */
+
+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 options - Cookie name string or options object
+   */
+  export function setLocale(
+    locale: string,
+    options?: string | {
+      cookieName?: string;
+      loadTranslations?: () => Promise<{ default?: Record<string, unknown> } | Record<string, unknown>>;
+    }
+  ): 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' {
+  /** Map of locale codes to their translation loaders */
+  export const translationLoaders: Record<
+    string,
+    () => Promise<{ default?: Record<string, unknown> } | Record<string, unknown>>
+  >;
+
+  /**
+   * Load translations for a specific locale
+   * @param locale - Locale code to load translations for
+   * @returns Translations object or empty object if not found
+   */
+  export function loadTranslations(locale: string): Promise<Record<string, unknown>>;
+}

package/src/vite-plugin.ts

@@ -0,0 +1,146 @@
+import type { Plugin } from 'vite';
+import type { EzI18nConfig, ResolvedEzI18nConfig } from './types';
+
+const VIRTUAL_CONFIG = 'ez-i18n:config';
+const VIRTUAL_RUNTIME = 'ez-i18n:runtime';
+const VIRTUAL_TRANSLATIONS = 'ez-i18n:translations';
+const RESOLVED_PREFIX = '\0';
+
+/**
+ * Resolve config with defaults
+ */
+export function resolveConfig(config: EzI18nConfig): ResolvedEzI18nConfig {
+  return {
+    locales: config.locales,
+    defaultLocale: config.defaultLocale,
+    cookieName: config.cookieName ?? 'ez-locale',
+    translations: config.translations ?? {},
+  };
+}
+
+/**
+ * Vite plugin that provides virtual modules for ez-i18n
+ */
+export function vitePlugin(config: EzI18nConfig): Plugin {
+  const resolved = resolveConfig(config);
+
+  return {
+    name: 'ez-i18n-vite',
+    enforce: 'pre',
+
+    resolveId(id) {
+      if (id === VIRTUAL_CONFIG || id === VIRTUAL_RUNTIME || id === VIRTUAL_TRANSLATIONS) {
+        return RESOLVED_PREFIX + id;
+      }
+      return null;
+    },
+
+    load(id) {
+      // ez-i18n:config - Static config values
+      if (id === RESOLVED_PREFIX + VIRTUAL_CONFIG) {
+        return `
+export const locales = ${JSON.stringify(resolved.locales)};
+export const defaultLocale = ${JSON.stringify(resolved.defaultLocale)};
+export const cookieName = ${JSON.stringify(resolved.cookieName)};
+`;
+      }
+
+      // ez-i18n:runtime - Runtime exports for Astro files
+      if (id === RESOLVED_PREFIX + VIRTUAL_RUNTIME) {
+        return `
+import { effectiveLocale, translations, setLocale, initLocale } from '@zachhandley/ez-i18n/runtime';
+
+export { setLocale, initLocale };
+export { effectiveLocale as locale };
+
+/**
+ * Get nested value from object using dot notation
+ */
+function getNestedValue(obj, path) {
+  const keys = path.split('.');
+  let value = obj;
+  for (const key of keys) {
+    if (value == null || typeof value !== 'object') return undefined;
+    value = value[key];
+  }
+  return value;
+}
+
+/**
+ * Interpolate params into string
+ */
+function interpolate(str, params) {
+  if (!params) return str;
+  return str.replace(/\\{(\\w+)\\}/g, (match, key) => {
+    return key in params ? String(params[key]) : match;
+  });
+}
+
+/**
+ * Translate a key to the current locale
+ * @param key - Dot-notation key (e.g., 'common.welcome')
+ * @param params - Optional interpolation params
+ */
+export function t(key, params) {
+  const trans = translations.get();
+  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);
+}
+`;
+      }
+
+      // ez-i18n:translations - Translation loaders
+      if (id === RESOLVED_PREFIX + VIRTUAL_TRANSLATIONS) {
+        // Generate dynamic import statements for each locale
+        const loaderEntries = Object.entries(resolved.translations)
+          .map(([locale, path]) => `  ${JSON.stringify(locale)}: () => import(${JSON.stringify(path)})`)
+          .join(',\n');
+
+        return `
+/**
+ * Translation loaders for ez-i18n
+ * Auto-generated from config
+ */
+export const translationLoaders = {
+${loaderEntries}
+};
+
+/**
+ * Load translations for a specific locale
+ * @param locale - Locale code to load translations for
+ * @returns Translations object or empty object if not found
+ */
+export async function loadTranslations(locale) {
+  const loader = translationLoaders[locale];
+  if (!loader) {
+    if (import.meta.env.DEV) {
+      console.warn('[ez-i18n] No translations configured for locale:', locale);
+    }
+    return {};
+  }
+
+  try {
+    const mod = await loader();
+    return mod.default ?? mod;
+  } catch (error) {
+    if (import.meta.env.DEV) {
+      console.error('[ez-i18n] Failed to load translations for locale:', locale, error);
+    }
+    return {};
+  }
+}
+`;
+      }
+
+      return null;
+    },
+  };
+}