@zachhandley/ez-i18n 0.1.1 → 0.1.3

package/src/runtime/react-plugin.ts

@@ -0,0 +1,78 @@
+import { useStore } from '@nanostores/react';
+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;
+  });
+}
+
+/**
+ * React hook for i18n
+ *
+ * @example
+ * import { useI18n } from '@zachhandley/ez-i18n/react';
+ *
+ * function MyComponent() {
+ *   const { t, locale, setLocale } = useI18n();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{t('common.welcome')}</h1>
+ *       <p>{t('greeting', { name: 'World' })}</p>
+ *       <button onClick={() => setLocale('es')}>Español</button>
+ *     </div>
+ *   );
+ * }
+ */
+export function useI18n() {
+  const locale = useStore(effectiveLocale);
+  const trans = useStore(translations);
+
+  const t: TranslateFunction = (
+    key: string,
+    params?: Record<string, string | number>
+  ): string => {
+    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);
+  };
+
+  return {
+    t,
+    locale,
+    setLocale,
+  };
+}

package/src/types.ts

@@ -1,14 +1,33 @@
+/**
+ * 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[];
+  locales?: string[];
 
   /**
-   * Default locale to use when no preference is detected
+   * Default locale to use when no preference is detected.
+   * Required - this tells us what to fall back to.
    */
   defaultLocale: string;
 
@@ -19,26 +38,52 @@ export interface EzI18nConfig {
   cookieName?: string;
 
   /**
-   * Translation file paths for each locale.
+   * Translation file paths configuration.
    * 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',
-   * }
+   *
+   * 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?: Record<string, string>;
+  translations?: TranslationsConfig;
 }
 
 /**
- * Resolved config with defaults applied
+ * 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;
-  translations: Record<string, string>;
+  /** Normalized: locale → array of resolved absolute file paths */
+  translations: 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;
 }
 
 /**

package/src/utils/index.ts

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

package/src/utils/translations.ts

@@ -0,0 +1,311 @@
+import { glob } from 'tinyglobby';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import type { LocaleTranslationPath, TranslationsConfig, TranslationCache } from '../types';
+
+const CACHE_FILE = '.ez-i18n.json';
+const CACHE_VERSION = 1;
+const DEFAULT_I18N_DIR = './public/i18n';
+
+export type PathType = 'file' | 'folder' | 'glob' | 'array';
+
+/**
+ * Detect the type of translation path
+ */
+export function detectPathType(input: string | string[]): PathType {
+  if (Array.isArray(input)) return 'array';
+  if (input.includes('*')) return 'glob';
+  if (input.endsWith('/') || input.endsWith(path.sep)) return 'folder';
+  return 'file';
+}
+
+/**
+ * Check if a path is a directory (handles missing trailing slash)
+ */
+function isDirectory(filePath: string): boolean {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a single translation path to an array of absolute file paths.
+ * Results are sorted alphabetically for predictable merge order.
+ */
+export async function resolveTranslationPaths(
+  input: LocaleTranslationPath,
+  projectRoot: string
+): Promise<string[]> {
+  const type = detectPathType(input);
+  let files: string[] = [];
+
+  switch (type) {
+    case 'array':
+      // Each entry could itself be a glob, folder, or file
+      for (const entry of input as string[]) {
+        const resolved = await resolveTranslationPaths(entry, projectRoot);
+        files.push(...resolved);
+      }
+      break;
+
+    case 'glob':
+      files = await glob(input as string, {
+        cwd: projectRoot,
+        absolute: true,
+      });
+      break;
+
+    case 'folder': {
+      const folderPath = path.resolve(projectRoot, (input as string).replace(/\/$/, ''));
+      files = await glob('**/*.json', {
+        cwd: folderPath,
+        absolute: true,
+      });
+      break;
+    }
+
+    case 'file':
+    default: {
+      const filePath = path.resolve(projectRoot, input as string);
+      // Check if it's actually a directory (user omitted trailing slash)
+      if (isDirectory(filePath)) {
+        files = await glob('**/*.json', {
+          cwd: filePath,
+          absolute: true,
+        });
+      } else {
+        files = [filePath];
+      }
+      break;
+    }
+  }
+
+  // Sort alphabetically for predictable merge order
+  return [...new Set(files)].sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Auto-discover translations from a base directory.
+ * Scans for locale folders (e.g., en/, es/, fr/) and their JSON files.
+ * Returns both discovered locales and their file mappings.
+ */
+export async function autoDiscoverTranslations(
+  baseDir: string,
+  projectRoot: string,
+  configuredLocales?: string[]
+): Promise<{ locales: string[]; translations: Record<string, string[]> }> {
+  const absoluteBaseDir = path.resolve(projectRoot, baseDir.replace(/\/$/, ''));
+
+  if (!isDirectory(absoluteBaseDir)) {
+    console.warn(`[ez-i18n] Translation directory not found: ${absoluteBaseDir}`);
+    return { locales: configuredLocales || [], translations: {} };
+  }
+
+  const translations: Record<string, string[]> = {};
+  const discoveredLocales: string[] = [];
+
+  // Read directory entries
+  const entries = fs.readdirSync(absoluteBaseDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      // This is a locale folder (e.g., en/, es/)
+      const locale = entry.name;
+
+      // If locales were configured, only include matching ones
+      if (configuredLocales && configuredLocales.length > 0) {
+        if (!configuredLocales.includes(locale)) continue;
+      }
+
+      const localePath = path.join(absoluteBaseDir, locale);
+      const files = await glob('**/*.json', {
+        cwd: localePath,
+        absolute: true,
+      });
+
+      if (files.length > 0) {
+        discoveredLocales.push(locale);
+        translations[locale] = files.sort((a, b) => a.localeCompare(b));
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.json')) {
+      // Root-level JSON files (e.g., en.json, es.json)
+      // Extract locale from filename
+      const locale = path.basename(entry.name, '.json');
+
+      // If locales were configured, only include matching ones
+      if (configuredLocales && configuredLocales.length > 0) {
+        if (!configuredLocales.includes(locale)) continue;
+      }
+
+      const filePath = path.join(absoluteBaseDir, entry.name);
+
+      if (!translations[locale]) {
+        discoveredLocales.push(locale);
+        translations[locale] = [];
+      }
+      translations[locale].push(filePath);
+    }
+  }
+
+  // Sort locales for consistency
+  const sortedLocales = [...new Set(discoveredLocales)].sort();
+
+  return { locales: sortedLocales, translations };
+}
+
+/**
+ * Resolve the full translations config to normalized form.
+ * Handles string (base dir), object (per-locale), or undefined (auto-discover).
+ */
+export async function resolveTranslationsConfig(
+  config: TranslationsConfig | undefined,
+  projectRoot: string,
+  configuredLocales?: string[]
+): Promise<{ locales: string[]; translations: Record<string, string[]> }> {
+  // No config - auto-discover from default location
+  if (!config) {
+    return autoDiscoverTranslations(DEFAULT_I18N_DIR, projectRoot, configuredLocales);
+  }
+
+  // String - treat as base directory for auto-discovery
+  if (typeof config === 'string') {
+    return autoDiscoverTranslations(config, projectRoot, configuredLocales);
+  }
+
+  // Object - per-locale mapping
+  const translations: Record<string, string[]> = {};
+  const locales = Object.keys(config);
+
+  for (const [locale, localePath] of Object.entries(config)) {
+    translations[locale] = await resolveTranslationPaths(localePath, projectRoot);
+  }
+
+  return { locales, translations };
+}
+
+/**
+ * Deep merge translation objects.
+ * - Objects are recursively merged
+ * - Arrays are REPLACED (not concatenated)
+ * - Primitives are overwritten by later values
+ * - Prototype pollution safe
+ */
+export function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  ...sources: T[]
+): T {
+  const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+  const result = { ...target };
+
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') continue;
+
+    for (const key of Object.keys(source)) {
+      if (FORBIDDEN_KEYS.has(key)) continue;
+
+      const targetVal = result[key as keyof T];
+      const sourceVal = source[key as keyof T];
+
+      if (
+        sourceVal !== null &&
+        typeof sourceVal === 'object' &&
+        !Array.isArray(sourceVal) &&
+        targetVal !== null &&
+        typeof targetVal === 'object' &&
+        !Array.isArray(targetVal)
+      ) {
+        // Both are plain objects - recurse
+        (result as Record<string, unknown>)[key] = deepMerge(
+          targetVal as Record<string, unknown>,
+          sourceVal as Record<string, unknown>
+        );
+      } else {
+        // Arrays replace, primitives overwrite
+        (result as Record<string, unknown>)[key] = sourceVal;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load cached translation discovery results
+ */
+export function loadCache(projectRoot: string): TranslationCache | null {
+  const cachePath = path.join(projectRoot, CACHE_FILE);
+
+  try {
+    if (!fs.existsSync(cachePath)) return null;
+
+    const content = fs.readFileSync(cachePath, 'utf-8');
+    const cache = JSON.parse(content) as TranslationCache;
+
+    // Validate cache version
+    if (cache.version !== CACHE_VERSION) return null;
+
+    return cache;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save translation discovery results to cache
+ */
+export function saveCache(
+  projectRoot: string,
+  discovered: Record<string, string[]>
+): void {
+  const cachePath = path.join(projectRoot, CACHE_FILE);
+
+  const cache: TranslationCache = {
+    version: CACHE_VERSION,
+    discovered,
+    lastScan: new Date().toISOString(),
+  };
+
+  try {
+    fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+  } catch (error) {
+    console.warn('[ez-i18n] Failed to write cache file:', error);
+  }
+}
+
+/**
+ * Check if cache is still valid (files haven't changed)
+ */
+export function isCacheValid(
+  cache: TranslationCache,
+  projectRoot: string
+): boolean {
+  // Check if all cached files still exist
+  for (const files of Object.values(cache.discovered)) {
+    for (const file of files) {
+      if (!fs.existsSync(file)) return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Convert an absolute path to a relative import path for Vite
+ */
+export function toRelativeImport(absolutePath: string, projectRoot: string): string {
+  const relativePath = path.relative(projectRoot, absolutePath);
+  // Ensure it starts with ./ and uses forward slashes
+  const normalized = relativePath.replace(/\\/g, '/');
+  return normalized.startsWith('.') ? normalized : './' + normalized;
+}
+
+/**
+ * Generate a glob pattern for import.meta.glob from a base directory
+ */
+export function toGlobPattern(baseDir: string, projectRoot: string): string {
+  const relativePath = path.relative(projectRoot, baseDir).replace(/\\/g, '/');
+  const normalized = relativePath.startsWith('.') ? relativePath : './' + relativePath;
+  return `${normalized}/**/*.json`;
+}