@zachhandley/ez-i18n 0.3.6 → 0.3.7

package/README.md

@@ -83,10 +83,12 @@ await setLocale('es');
 Core translation functions:
 
 ```ts
-import { t, locale, setLocale, initLocale } from 'ez-i18n:runtime';
+import { t, tc, locale, setLocale, initLocale } from 'ez-i18n:runtime';
 
 t('key');                    // Translate a key
 t('key', { name: 'World' }); // With interpolation
+tc('key');                   // Returns ReadableAtom<string> for reactive subscriptions
+tc('key', { name: 'World' }); // With interpolation (reactive)
 locale;                      // Reactive store with current locale
 await setLocale('es');       // Change locale (persists to cookie)
 initLocale('en', data);      // Initialize with translations
@@ -117,6 +119,28 @@ import { loadTranslations, translationLoaders } from 'ez-i18n:translations';
 const data = await loadTranslations('es');
 ```
 
+## Reactive Translations with tc()
+
+The `tc()` function returns a nanostore computed atom (`ReadableAtom<string>`) that automatically updates when the locale or translation data changes. This is useful when:
+
+- Translations may load asynchronously after component mount
+- You need fine-grained reactivity for specific translation keys
+- Using with framework bindings (Vue/React) that need reactive subscriptions
+
+```ts
+import { tc } from 'ez-i18n:runtime';
+import { useStore } from '@nanostores/react'; // or @nanostores/vue
+
+// Returns a ReadableAtom that updates when locale changes
+const title = tc('welcome.title');
+const greeting = tc('welcome.message', { name: 'Alice' });
+
+// In React/Vue, use with framework-specific store hooks
+const titleValue = useStore(title); // Automatically re-renders on locale change
+```
+
+For most use cases, the regular `t()` function is sufficient. Use `tc()` when you need explicit reactive subscriptions in your framework code.
+
 ## Locale Utilities
 
 The package includes a comprehensive locale database with 100+ languages:

package/dist/index.js

@@ -501,6 +501,7 @@ export const localeDirections = ${JSON.stringify(localeDirections)};
       }
       if (id === RESOLVED_PREFIX + VIRTUAL_RUNTIME) {
         return `
+import { computed } from 'nanostores';
 import { effectiveLocale, translations, setLocale, initLocale } from '@zachhandley/ez-i18n/runtime';
 
 export { setLocale, initLocale };
@@ -530,7 +531,7 @@ function interpolate(str, params) {
 }
 
 /**
- * Translate a key to the current locale
+ * Translate a key to the current locale (non-reactive)
  * @param key - Dot-notation key (e.g., 'common.welcome')
  * @param params - Optional interpolation params
  */
@@ -547,6 +548,26 @@ export function t(key, params) {
 
   return interpolate(value, params);
 }
+
+/**
+ * Create a reactive translation computed (nanostore computed atom)
+ * @param key - Dot-notation key (e.g., 'common.welcome')
+ * @param params - Optional interpolation params
+ */
+export function tc(key, params) {
+  return computed(translations, (trans) => {
+    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);
+  });
+}
 `;
       }
       if (id === RESOLVED_PREFIX + VIRTUAL_TRANSLATIONS) {

package/dist/runtime/index.d.ts

@@ -1,5 +1,16 @@
 import * as nanostores from 'nanostores';
+import { ReadableAtom } from 'nanostores';
 
+/**
+ * Get nested value from object using dot notation
+ * @example getNestedValue({ a: { b: 'hello' } }, 'a.b') // 'hello'
+ */
+declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Interpolate params into string using {placeholder} syntax
+ * @example interpolate('Hello {name}!', { name: 'World' }) // 'Hello World!'
+ */
+declare function interpolate(str: string, params?: Record<string, string | number>): string;
 /**
  * Client-side locale preference (persisted to localStorage)
  */
@@ -7,7 +18,7 @@ declare const localePreference: nanostores.WritableAtom<string>;
 /**
  * Effective locale - uses server locale if set, otherwise client preference
  */
-declare const effectiveLocale: nanostores.ReadableAtom<string>;
+declare const effectiveLocale: ReadableAtom<string>;
 /**
  * Current translations object (reactive)
  */
@@ -48,5 +59,34 @@ declare function getLocale(): string;
  * Get current translations (non-reactive)
  */
 declare function getTranslations(): Record<string, unknown>;
+/**
+ * Translate a key to its value (non-reactive, imperative)
+ * Use this in event handlers, callbacks, or non-reactive contexts.
+ *
+ * @example
+ * const message = t('welcome.title');
+ * const greeting = t('welcome.hello', { name: 'World' });
+ */
+declare function t(key: string, params?: Record<string, string | number>): string;
+/**
+ * Create a reactive translation computed (nanostore computed atom)
+ * Returns a ReadableAtom<string> that updates when translations change.
+ *
+ * Use this when you need a reactive translation that updates automatically:
+ * - In Vue/React components where translations may load after initial render
+ * - When locale changes should trigger re-renders
+ * - To avoid hydration mismatches in SSR
+ *
+ * @example
+ * // Static key
+ * const $title = tc('welcome.title');
+ *
+ * // In Vue (with @nanostores/vue)
+ * const title = useStore(tc('welcome.title'));
+ *
+ * // In React (with @nanostores/react)
+ * const title = useStore(tc('welcome.title'));
+ */
+declare function tc(key: string, params?: Record<string, string | number>): ReadableAtom<string>;
 
-export { type TranslationLoader, effectiveLocale, getLocale, getTranslations, initLocale, localeLoading, localePreference, setLocale, setTranslations, translations };
+export { type TranslationLoader, effectiveLocale, getLocale, getNestedValue, getTranslations, initLocale, interpolate, localeLoading, localePreference, setLocale, setTranslations, t, tc, translations };

package/dist/runtime/index.js

@@ -1,6 +1,23 @@
 // src/runtime/store.ts
 import { atom, computed } from "nanostores";
 import { persistentAtom } from "@nanostores/persistent";
+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;
+  });
+}
 var serverLocale = atom(null);
 var localePreference = persistentAtom("ez-locale", "en", {
   encode: (value) => value,
@@ -61,14 +78,41 @@ function getLocale() {
 function getTranslations() {
   return translations.get();
 }
+function t(key, params) {
+  const trans = translations.get();
+  const value = getNestedValue(trans, key);
+  if (typeof value !== "string") {
+    if (typeof import.meta !== "undefined" && import.meta.env?.DEV) {
+      console.warn("[ez-i18n] Missing translation:", key);
+    }
+    return key;
+  }
+  return interpolate(value, params);
+}
+function tc(key, params) {
+  return computed(translations, (trans) => {
+    const value = getNestedValue(trans, key);
+    if (typeof value !== "string") {
+      if (typeof import.meta !== "undefined" && import.meta.env?.DEV) {
+        console.warn("[ez-i18n] Missing translation:", key);
+      }
+      return key;
+    }
+    return interpolate(value, params);
+  });
+}
 export {
   effectiveLocale,
   getLocale,
+  getNestedValue,
   getTranslations,
   initLocale,
+  interpolate,
   localeLoading,
   localePreference,
   setLocale,
   setTranslations,
+  t,
+  tc,
   translations
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zachhandley/ez-i18n",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "publishConfig": {
     "access": "public"
   },