@zachhandley/ez-i18n 0.2.2 → 0.3.0

package/README.md

@@ -1,371 +0,0 @@
-# @zachhandley/ez-i18n
-
-Cookie-based i18n for Astro + Vue + React. No URL prefixes, reactive language switching.
-
-## Installation
-
-```bash
-pnpm add @zachhandley/ez-i18n nanostores @nanostores/persistent
-
-# If using Vue:
-pnpm add @nanostores/vue
-
-# If using React:
-pnpm add @nanostores/react
-```
-
-## Usage
-
-### Astro Config
-
-```typescript
-// astro.config.ts
-import { defineConfig } from 'astro/config';
-import vue from '@astrojs/vue';
-import ezI18n from '@zachhandley/ez-i18n';
-
-export default defineConfig({
-  integrations: [
-    vue(),
-    ezI18n({
-      locales: ['en', 'es', 'fr'],
-      defaultLocale: 'en',
-      cookieName: 'my-locale', // optional, defaults to 'ez-locale'
-      translations: {
-        en: './src/i18n/en.json',
-        es: './src/i18n/es.json',
-        fr: './src/i18n/fr.json',
-      },
-    }),
-  ],
-});
-```
-
-### Translation Files
-
-```json
-{
-  "common": {
-    "welcome": "Welcome",
-    "save": "Save",
-    "cancel": "Cancel"
-  },
-  "auth": {
-    "login": "Log in",
-    "signup": "Sign up"
-  }
-}
-```
-
-Create similar files for each locale: `src/i18n/en.json`, `src/i18n/es.json`, etc.
-
-### Multi-File Translations
-
-ez-i18n supports flexible translation file organization:
-
-#### Auto-Discovery (Zero Config)
-
-Just put your files in `public/i18n/` and ez-i18n will discover them automatically:
-
-```
-public/i18n/
-  en/
-    common.json
-    auth.json
-  es/
-    common.json
-    auth.json
-```
-
-```typescript
-// astro.config.ts - locales auto-discovered from folder names!
-ezI18n({
-  defaultLocale: 'en',
-  // No locales or translations needed - auto-discovered
-})
-```
-
-#### Base Directory
-
-Point to a folder and locales are discovered from subfolders:
-
-```typescript
-ezI18n({
-  defaultLocale: 'en',
-  translations: './src/i18n/',  // Discovers en/, es/, fr/ folders
-})
-```
-
-#### Per-Locale with Multiple Formats
-
-Mix and match different formats per locale:
-
-```typescript
-ezI18n({
-  locales: ['en', 'es', 'fr', 'de'],
-  defaultLocale: 'en',
-  translations: {
-    en: './src/i18n/en.json',              // Single file
-    es: './src/i18n/es/',                   // Folder (all JSONs merged)
-    fr: './src/i18n/fr/**/*.json',          // Glob pattern
-    de: ['./src/i18n/de/common.json',       // Array of files
-         './src/i18n/de/auth.json'],
-  },
-})
-```
-
-#### Merge Order
-
-When using multiple files per locale, files are merged **alphabetically by filename**. Later files override earlier ones for conflicting keys.
-
-```
-en/
-  01-common.json    # Loaded first
-  02-features.json  # Loaded second, overrides common
-  99-overrides.json # Loaded last, highest priority
-```
-
-#### Path-Based Namespacing
-
-When using folder-based translation organization, ez-i18n automatically creates namespaces from your file paths. This is **enabled by default** when using folder-based config.
-
-**Example:**
-
-```
-public/i18n/
-  en/
-    auth/
-      login.json     # { "title": "Sign In", "button": "Log In" }
-      signup.json    # { "title": "Create Account" }
-    common.json      # { "welcome": "Welcome" }
-```
-
-Access translations using dot notation that mirrors the folder structure:
-
-```typescript
-$t('auth.login.title')     // "Sign In"
-$t('auth.login.button')    // "Log In"
-$t('auth.signup.title')    // "Create Account"
-$t('common.welcome')       // "Welcome"
-```
-
-**Disable path-based namespacing:**
-
-If you prefer to manage namespaces manually within your JSON files, you can disable this feature:
-
-```typescript
-ezI18n({
-  defaultLocale: 'en',
-  translations: './src/i18n/',
-  pathBasedNamespacing: false,  // Disable automatic path namespacing
-})
-```
-
-With `pathBasedNamespacing: false`, the file structure is ignored and keys are used directly from each JSON file.
-
-#### Cache File
-
-A `.ez-i18n.json` cache file is generated to speed up subsequent builds. Add it to `.gitignore`:
-
-```gitignore
-.ez-i18n.json
-```
-
-### Layout Setup
-
-Add the `EzI18nHead` component to your layout's head for automatic hydration:
-
-```astro
----
-// src/layouts/Layout.astro
-import EzI18nHead from '@zachhandley/ez-i18n/astro';
-const { locale, translations } = Astro.locals;
----
-
-<html lang={locale}>
-  <head>
-    <meta charset="utf-8" />
-    <EzI18nHead locale={locale} translations={translations} />
-  </head>
-  <body>
-    <slot />
-  </body>
-</html>
-```
-
-### In Astro Files
-
-```astro
----
-import { t, locale } from 'ez-i18n:runtime';
-// Or access from locals (auto-loaded by middleware):
-const { locale, translations } = Astro.locals;
----
-
-<h1>{t('common.welcome')}</h1>
-<p>Current locale: {locale}</p>
-```
-
-### In Vue Components
-
-```vue
-<script setup lang="ts">
-import { useI18n } from '@zachhandley/ez-i18n/vue';
-import { translationLoaders } from 'ez-i18n:translations';
-
-const { t, locale, setLocale } = useI18n();
-
-// Change locale with dynamic translation loading
-async function switchLocale(newLocale: string) {
-  await setLocale(newLocale, {
-    loadTranslations: translationLoaders[newLocale],
-  });
-}
-</script>
-
-<template>
-  <!-- Global $t is available automatically -->
-  <h1>{{ $t('common.welcome') }}</h1>
-
-  <!-- Interpolation -->
-  <p>{{ $t('greeting', { name: 'World' }) }}</p>
-
-  <!-- Change language with dynamic loading -->
-  <button @click="switchLocale('es')">Español</button>
-  <button @click="switchLocale('fr')">Français</button>
-</template>
-```
-
-### Vue Plugin Setup
-
-Register the Vue plugin in your entrypoint:
-
-```typescript
-// src/_vueEntrypoint.ts
-import type { App } from 'vue';
-import { ezI18nVue } from '@zachhandley/ez-i18n/vue';
-
-export default (app: App) => {
-  app.use(ezI18nVue);
-};
-```
-
-### In React Components
-
-```tsx
-import { useI18n } from '@zachhandley/ez-i18n/react';
-import { translationLoaders } from 'ez-i18n:translations';
-
-function MyComponent() {
-  const { t, locale, setLocale } = useI18n();
-
-  async function switchLocale(newLocale: string) {
-    await setLocale(newLocale, {
-      loadTranslations: translationLoaders[newLocale],
-    });
-  }
-
-  return (
-    <div>
-      <h1>{t('common.welcome')}</h1>
-      <p>{t('greeting', { name: 'World' })}</p>
-      <button onClick={() => switchLocale('es')}>Español</button>
-      <button onClick={() => switchLocale('fr')}>Français</button>
-    </div>
-  );
-}
-```
-
-## Features
-
-- **No URL prefixes** - Locale stored in cookie, not URL path
-- **Reactive** - Language changes update immediately without page reload
-- **SSR compatible** - Proper hydration with server-rendered locale
-- **Vue integration** - Global `$t()`, `$locale`, `$setLocale` in templates
-- **React integration** - `useI18n()` hook for React components
-- **Middleware included** - Auto-detects locale from cookie, query param, or Accept-Language header
-- **Multi-file support** - Organize translations in folders, use globs, or arrays
-- **Auto-discovery** - Automatic locale detection from folder structure
-- **Path-based namespacing** - Automatic namespacing from folder structure (`auth/login.json` becomes `auth.login.*`)
-- **HMR in dev** - Hot reload translation changes without restart
-
-## Locale Detection Priority
-
-1. `?lang=xx` query parameter
-2. Cookie value
-3. Accept-Language header
-4. Default locale
-
-## API
-
-### `ezI18n(config)`
-
-Astro integration function.
-
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `locales` | `string[]` | No | Supported locale codes (auto-discovered if not provided) |
-| `defaultLocale` | `string` | Yes | Fallback locale |
-| `cookieName` | `string` | No | Cookie name (default: `'ez-locale'`) |
-| `translations` | `string \| Record<string, TranslationPath>` | No | Base directory or per-locale paths (default: `./public/i18n/`) |
-| `pathBasedNamespacing` | `boolean` | No | Auto-namespace translations from folder paths (default: `true` for folder-based config) |
-
-**TranslationPath** can be:
-- Single file: `'./src/i18n/en.json'`
-- Folder: `'./src/i18n/en/'`
-- Glob: `'./src/i18n/en/**/*.json'`
-- Array: `['./common.json', './auth.json']`
-
-### `EzI18nHead`
-
-Astro component for i18n hydration. Place in your layout's `<head>`.
-
-```astro
-<EzI18nHead locale={Astro.locals.locale} translations={Astro.locals.translations} />
-```
-
-### `$t(key, params?)`
-
-Translate a key with optional interpolation.
-
-```typescript
-$t('greeting'); // "Hello"
-$t('greeting', { name: 'World' }); // "Hello, {name}" -> "Hello, World"
-```
-
-### `setLocale(locale, options?)`
-
-Change the current locale. Updates cookie and triggers reactive update.
-
-```typescript
-// Simple usage
-setLocale('es');
-
-// With dynamic translation loading
-import { translationLoaders } from 'ez-i18n:translations';
-setLocale('es', { loadTranslations: translationLoaders['es'] });
-```
-
-### `useI18n()`
-
-Hook for Vue (Composition API) and React.
-
-```typescript
-// Vue
-import { useI18n } from '@zachhandley/ez-i18n/vue';
-
-// React
-import { useI18n } from '@zachhandley/ez-i18n/react';
-
-const { t, locale, setLocale } = useI18n();
-```
-
-### Virtual Modules
-
-- `ez-i18n:config` - Static config (locales, defaultLocale, cookieName)
-- `ez-i18n:runtime` - Runtime functions (t, setLocale, initLocale, locale store)
-- `ez-i18n:translations` - Translation loaders (loadTranslations, translationLoaders)
-
-## License
-
-MIT

package/dist/runtime/react-plugin.d.ts

@@ -1,28 +0,0 @@
-import { setLocale } from '@zachhandley/ez-i18n/runtime';
-import { T as TranslateFunction } from '../types-Cd9e7Lkc.js';
-
-/**
- * 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>
- *   );
- * }
- */
-declare function useI18n(): {
-    t: TranslateFunction;
-    locale: string;
-    setLocale: typeof setLocale;
-};
-
-export { useI18n };

package/dist/runtime/react-plugin.js

@@ -1,42 +0,0 @@
-// src/runtime/react-plugin.ts
-import { useStore } from "@nanostores/react";
-import { effectiveLocale, translations, setLocale } from "@zachhandley/ez-i18n/runtime";
-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 useI18n() {
-  const locale = useStore(effectiveLocale);
-  const trans = useStore(translations);
-  const t = (key, params) => {
-    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
-  };
-}
-export {
-  useI18n
-};

package/dist/runtime/vue-plugin.d.ts

@@ -1,51 +0,0 @@
-import * as vue from 'vue';
-import { Plugin } from 'vue';
-import { setLocale } from '@zachhandley/ez-i18n/runtime';
-import { T as TranslateFunction } from '../types-Cd9e7Lkc.js';
-
-/**
- * Vue plugin that provides global $t(), $locale, and $setLocale
- *
- * @example
- * // In _vueEntrypoint.ts or main.ts
- * import { ezI18nVue } from '@zachhandley/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>
- */
-declare const ezI18nVue: Plugin;
-/**
- * Composable for using i18n in Vue components with Composition API
- *
- * @example
- * <script setup>
- * import { useI18n } from '@zachhandley/ez-i18n/vue';
- *
- * const { t, locale, setLocale } = useI18n();
- * const greeting = t('welcome.greeting');
- * </script>
- */
-declare function useI18n(): {
-    t: TranslateFunction;
-    locale: Readonly<vue.Ref<string, string>>;
-    setLocale: typeof setLocale;
-};
-declare module 'vue' {
-    interface ComponentCustomProperties {
-        $t: TranslateFunction;
-        /** Current locale (reactive ref from nanostore) */
-        $locale: Readonly<vue.Ref<string>>;
-        $setLocale: typeof setLocale;
-    }
-}
-
-export { ezI18nVue as default, ezI18nVue, useI18n };

package/dist/runtime/vue-plugin.js

@@ -1,67 +0,0 @@
-// src/runtime/vue-plugin.ts
-import { computed } from "vue";
-import { useStore } from "@nanostores/vue";
-import { effectiveLocale, translations, setLocale } from "@zachhandley/ez-i18n/runtime";
-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 = computed(() => 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 = computed(() => trans.value);
-  const t = createTranslateFunction(transComputed);
-  return {
-    t,
-    locale,
-    setLocale
-  };
-}
-var vue_plugin_default = ezI18nVue;
-export {
-  vue_plugin_default as default,
-  ezI18nVue,
-  useI18n
-};

package/src/runtime/react-plugin.ts

@@ -1,79 +0,0 @@
-import { useStore } from '@nanostores/react';
-// Import from package path (not relative) to ensure shared store instance
-import { effectiveLocale, translations, setLocale } from '@zachhandley/ez-i18n/runtime';
-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,
-  };
-}