@babelize/sdk 0.0.1

package/README.md

@@ -0,0 +1,333 @@
+# @babelize/sdk
+
+**Core runtime for Babelize** — wrap strings, translate, cache, done. No translation keys, no locale files, no configuration.
+
+```ts
+import { babelize } from "@babelize/sdk";
+
+babelize.init(process.env.BABELIZE_API_KEY);
+
+babelize("Welcome");                    // "ようこそ"
+babelize("Hello {name}", { name });     // "こんにちは Mohit"
+babelize.p("{count} item", "{count} items", 5); // "5 items"
+```
+
+---
+
+## Install
+
+```bash
+bun add @babelize/sdk
+```
+
+---
+
+## Quick Start
+
+```ts
+import { babelize } from "@babelize/sdk";
+
+// 1. Initialize
+babelize.init({
+  apiKey: process.env.BABELIZE_API_KEY,
+  locale: "ja",
+});
+
+// 2. Load production lockfile (generated at build time)
+import lockfile from "virtual:babelize-lockfile";
+lockfile && babelize.loadLockfile(lockfile);
+
+// 3. Get translations
+babelize("Welcome");                        // "バビリゾーンへようこそ"
+babelize("Hello {name}", { name: "World" }); // "こんにちは World"
+
+// 4. Switch locale
+babelize.setLocale("fr");
+babelize("Welcome");                        // "Bienvenue à Babelize"
+
+// 5. Get current locale
+const locale = babelize.getLocale();        // "fr"
+```
+
+### With React
+
+```tsx
+import { BabelizeProvider, useBabelize, useLocale } from "@babelize/sdk-react";
+
+// Wrap your app
+root.render(
+  <BabelizeProvider>
+    <App />
+  </BabelizeProvider>,
+);
+```
+
+---
+
+## API
+
+### `babelize(str, vars?)`
+
+Translate a string into the current locale.
+
+```ts
+babelize("Welcome");                       // "ようこそ"
+babelize("Hello {name}", { name: "Mohit" }); // "こんにちは Mohit"
+babelize("You have {count} messages", { count: 5 }); // "5件のメッセージがあります"
+```
+
+- Returns the translated string from cache or lockfile
+- Returns the original string if no translation is found
+- Background API call is queued if the string is not cached
+- `{key}` placeholders are interpolated with `vars`
+
+### `babelize.init(config)`
+
+Initialize the SDK. Accepts an API key string or a config object.
+
+```ts
+// With API key string
+babelize.init("blz_sk_...");
+
+// With config object
+babelize.init({
+  apiKey: "blz_sk_...",
+  locale: "ja",
+  fallbackLocale: "en",
+  apiUrl: "https://api.babelize.co/api",
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | — | Babelize API key (optional in production) |
+| `locale` | `string` | auto-detected | Initial locale |
+| `fallbackLocale` | `string` | `"en"` | Fallback when auto-detection fails |
+| `apiUrl` | `string` | `"https://api.babelize.co/api"` | API endpoint |
+
+### `babelize.setLocale(locale)`
+
+Switch the active locale. All subsequent `babelize()` calls use this locale. Triggers re-render in React components.
+
+```ts
+babelize.setLocale("fr");
+babelize.getLocale(); // "fr"
+```
+
+### `babelize.getLocale()`
+
+Returns the currently active locale.
+
+```ts
+const current = babelize.getLocale();
+```
+
+### `babelize.p(singular, plural, countOrVars)`
+
+Simple two-form pluralization. Uses [`Intl.PluralRules`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/PluralRules) to select the correct form for the current locale.
+
+```ts
+// With count as number
+babelize.p("{count} item", "{count} items", 1);  // "1 item" (one)
+babelize.p("{count} item", "{count} items", 5);  // "5 items" (other)
+
+// With vars object (count is extracted)
+babelize.p("{count} item", "{count} items", { count: items.length });
+
+// Polish automatically selects "few" for 2-4, "many" for 5+
+babelize.setLocale("pl");
+babelize.p("{count} element", "{count} elementów", 2);  // "2 elementy" (few)
+babelize.p("{count} element", "{count} elementów", 5);  // "5 elementów" (many)
+```
+
+### `babelize.plural(forms, vars?)`
+
+Explicit CLDR plural forms for full control. Supports all 6 CLDR forms: `zero`, `one`, `two`, `few`, `many`, `other`.
+
+```ts
+babelize.plural(
+  {
+    one: "{count} item",
+    other: "{count} items",
+  },
+  { count: 5 },
+);
+
+// Arabic has 6 forms
+babelize.setLocale("ar");
+babelize.plural(
+  {
+    zero: "لا {count} عناصر",
+    one: "{count} عنصر",
+    two: "{count} عنصرين",
+    few: "{count} عناصر",
+    many: "عنصر {count}",
+    other: "{count} عنصرًا",
+  },
+  { count: 0 },  // zero
+);
+```
+
+### `babelize.tag(template)`
+
+Translate a template string with segment markers as a single unit. The full sentence is sent to the translator, so word order and grammar are correct across segments.
+
+```ts
+const result = babelize.tag("Welcome to {Babelize}, a platform {for localization}");
+// result.parts = [
+//   { type: 'text', value: 'ローカリゼーションのための' },
+//   { type: 'segment', value: 'for localization' },
+//   { type: 'text', value: 'プラットフォーム、' },
+//   { type: 'segment', value: 'Babelize' },
+//   { type: 'text', value: 'へようこそ' },
+// ]
+
+// Map segments to React elements
+const segments = {
+  Babelize: <strong>Babelize</strong>,
+  "for localization": <em>for localization</em>,
+};
+const rendered = result.parts.map(p =>
+  p.type === 'segment' ? segments[p.value] ?? p.value : p.value,
+);
+```
+
+### `babelize.loadLockfile(data)`
+
+Load a pre-generated lockfile into the translation cache. The lockfile is generated at build time by the Vite plugin.
+
+```ts
+import lockfile from "virtual:babelize-lockfile";
+lockfile && babelize.loadLockfile(lockfile);
+```
+
+### `babelize.subscribe(cb)`
+
+Subscribe to state changes (locale switch, cache update). Returns an unsubscribe function.
+
+```ts
+const unsubscribe = babelize.subscribe(() => {
+  console.log("Locale or translation cache updated");
+});
+
+// Later
+unsubscribe();
+```
+
+### `babelize.getVersion()`
+
+Returns a number that increments on every state change. Useful with `useSyncExternalStore` for reactivity.
+
+```ts
+const version = babelize.getVersion();
+```
+
+### `babelize.reset()`
+
+Clear all state — cache, locale, subscribers, API client. Useful in testing.
+
+```ts
+babelize.reset();
+```
+
+---
+
+## Lockfile Format
+
+The lockfile is generated at build time by `@babelize/vite` or `@babelize/next`. In production, translations are read from the lockfile — zero API calls.
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "generatedAt": "2026-07-30T12:00:00Z",
+    "locales": ["ja", "fr", "de"],
+    "totalStrings": 42
+  },
+  "strings": {
+    "Welcome": {
+      "ja": "バビリゾーンへようこそ",
+      "fr": "Bienvenue à Babelize",
+      "de": "Willkommen bei Babelize"
+    },
+    "Hello {name}": {
+      "ja": "こんにちは {name}",
+      "fr": "Bonjour {name}",
+      "de": "Hallo {name}"
+    }
+  },
+  "plurals": {
+    "{count} item": {
+      "forms": ["one", "other"],
+      "ja": { "other": "{count} 項目" },
+      "fr": { "one": "{count} élément", "other": "{count} éléments" },
+      "de": { "one": "{count} Gegenstand", "other": "{count} Gegenstände" }
+    }
+  }
+}
+```
+
+---
+
+## Cache Strategy
+
+```
+Memory Cache      < 0.1ms
+    ↓ (miss)
+Lockfile Cache    < 1ms
+    ↓ (miss)
+Babelize API      < 100ms
+    ↓ (miss)
+Original string   (fallback)
+```
+
+- Memory cache is checked first for every `babelize()` call
+- Lockfile cache is loaded at startup from the build-time lockfile
+- API calls are batched via `queueMicrotask` — all strings from one render cycle are sent as a single request
+- Once a translation is returned by the API, it's cached in memory and never fetched again
+- Production builds read from lockfile only — zero API calls at runtime
+
+---
+
+## TypeScript
+
+```ts
+import type { BabelizeConfig, LockfileData, PluralForms, TagResult, TagPart } from "@babelize/sdk";
+
+interface BabelizeConfig {
+  apiKey?: string;
+  locale?: string;
+  fallbackLocale?: string;
+  apiUrl?: string;
+  storage?: TranslationStorage;
+}
+
+interface LockfileData {
+  version: number;
+  strings: Record<string, Record<string, string>>;
+  plurals?: Record<string, {
+    forms: string[];
+    [locale: string]: Record<string, string> | string[];
+  }>;
+}
+
+type PluralForms = {
+  zero?: string;
+  one?: string;
+  two?: string;
+  few?: string;
+  many?: string;
+  other: string;
+};
+
+interface TagResult {
+  parts: TagPart[];
+}
+
+interface TagPart {
+  type: "text" | "segment";
+  value: string;
+}
+```

package/dist/index.cjs

@@ -0,0 +1,451 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  babelize: () => babelize
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/storage/JsonStorage.ts
+var JsonStorage = class {
+  constructor() {
+    this.data = null;
+  }
+  load(data) {
+    this.data = data;
+  }
+  get(locale, key) {
+    if (!this.data) return null;
+    const translations = this.data.strings[key];
+    if (!translations) return null;
+    return translations[locale] ?? null;
+  }
+};
+
+// src/cache/Cache.ts
+var Cache = class {
+  constructor() {
+    this.memory = /* @__PURE__ */ new Map();
+    this.pluralMemory = /* @__PURE__ */ new Map();
+    this.pluralLockfile = /* @__PURE__ */ new Map();
+    this.lockfile = new JsonStorage();
+  }
+  loadLockfile(data) {
+    this.lockfile.load(data);
+    if (data.plurals) {
+      for (const [canonical, localeData] of Object.entries(data.plurals)) {
+        for (const [locale, forms] of Object.entries(localeData)) {
+          if (locale === "forms") continue;
+          const formMap = forms;
+          let localePlurals = this.pluralLockfile.get(locale);
+          if (!localePlurals) {
+            localePlurals = /* @__PURE__ */ new Map();
+            this.pluralLockfile.set(locale, localePlurals);
+          }
+          localePlurals.set(canonical, formMap);
+        }
+      }
+    }
+  }
+  get(locale, str) {
+    const localeCache = this.memory.get(locale);
+    if (localeCache?.has(str)) {
+      return localeCache.get(str);
+    }
+    const fromLockfile = this.lockfile.get(locale, str);
+    if (fromLockfile !== null) {
+      this.setMemory(locale, str, fromLockfile);
+      return fromLockfile;
+    }
+    return null;
+  }
+  set(locale, str, translation) {
+    this.setMemory(locale, str, translation);
+  }
+  getPlural(locale, key, form) {
+    const localePluralMemory = this.pluralMemory.get(locale);
+    if (localePluralMemory?.get(key)?.has(form)) {
+      return localePluralMemory.get(key).get(form);
+    }
+    const localePluralLockfile = this.pluralLockfile.get(locale);
+    if (localePluralLockfile?.has(key)) {
+      const forms = localePluralLockfile.get(key);
+      const translation = forms[form] ?? null;
+      if (translation !== null) {
+        let keyMemory = this.pluralMemory.get(locale);
+        if (!keyMemory) {
+          keyMemory = /* @__PURE__ */ new Map();
+          this.pluralMemory.set(locale, keyMemory);
+        }
+        let formMemory = keyMemory.get(key);
+        if (!formMemory) {
+          formMemory = /* @__PURE__ */ new Map();
+          keyMemory.set(key, formMemory);
+        }
+        formMemory.set(form, translation);
+        return translation;
+      }
+    }
+    return null;
+  }
+  setPlural(locale, key, form, translation) {
+    let localeMemory = this.pluralMemory.get(locale);
+    if (!localeMemory) {
+      localeMemory = /* @__PURE__ */ new Map();
+      this.pluralMemory.set(locale, localeMemory);
+    }
+    let keyMemory = localeMemory.get(key);
+    if (!keyMemory) {
+      keyMemory = /* @__PURE__ */ new Map();
+      localeMemory.set(key, keyMemory);
+    }
+    keyMemory.set(form, translation);
+  }
+  hasPlural(locale, key, form) {
+    if (this.pluralMemory.get(locale)?.get(key)?.has(form)) return true;
+    const lockfileForm = this.pluralLockfile.get(locale)?.get(key)?.[form];
+    return lockfileForm != null;
+  }
+  setMemory(locale, str, translation) {
+    let localeCache = this.memory.get(locale);
+    if (!localeCache) {
+      localeCache = /* @__PURE__ */ new Map();
+      this.memory.set(locale, localeCache);
+    }
+    localeCache.set(str, translation);
+  }
+  has(locale, str) {
+    return this.memory.get(locale)?.has(str) ?? this.lockfile.get(locale, str) !== null;
+  }
+};
+
+// src/api/client.ts
+var DEFAULT_API_URL = "https://api.babelize.co/api";
+var ApiClient = class {
+  constructor(apiKey, apiUrl = DEFAULT_API_URL) {
+    this.apiKey = apiKey;
+    this.apiUrl = apiUrl;
+  }
+  async translate(locale, strings, plurals) {
+    if (strings.length === 0 && !plurals?.length) return { translations: {} };
+    const response = await fetch(`${this.apiUrl}/v1/translate`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({ locale, strings, plurals })
+    });
+    if (!response.ok) {
+      throw new Error(`Translation API error: ${response.status}`);
+    }
+    return response.json();
+  }
+};
+
+// src/batching/Batcher.ts
+var Batcher = class {
+  constructor(flushFn) {
+    this.pending = /* @__PURE__ */ new Map();
+    this.pendingPlurals = /* @__PURE__ */ new Map();
+    this.scheduled = false;
+    this.flushFn = flushFn;
+  }
+  add(locale, str) {
+    if (!this.pending.has(locale)) {
+      this.pending.set(locale, /* @__PURE__ */ new Set());
+    }
+    this.pending.get(locale).add(str);
+    if (!this.scheduled) {
+      this.scheduled = true;
+      queueMicrotask(() => this.flush());
+    }
+  }
+  addPlural(locale, canonical, forms, templates) {
+    if (!this.pendingPlurals.has(locale)) {
+      this.pendingPlurals.set(locale, []);
+    }
+    this.pendingPlurals.get(locale).push({ canonical, forms, templates });
+    if (!this.scheduled) {
+      this.scheduled = true;
+      queueMicrotask(() => this.flush());
+    }
+  }
+  async flush() {
+    this.scheduled = false;
+    const batch = this.pending;
+    const batchPlurals = this.pendingPlurals;
+    this.pending = /* @__PURE__ */ new Map();
+    this.pendingPlurals = /* @__PURE__ */ new Map();
+    const promises = [];
+    for (const [locale, strings] of batch) {
+      const plurals = batchPlurals.get(locale);
+      if (strings.size === 0 && !plurals?.length) continue;
+      promises.push(this.flushFn(locale, [...strings], plurals));
+    }
+    for (const [locale, plurals] of batchPlurals) {
+      if (batch.has(locale)) continue;
+      if (!plurals.length) continue;
+      promises.push(this.flushFn(locale, [], plurals));
+    }
+    await Promise.all(promises);
+  }
+};
+
+// src/locale/detect.ts
+function browserDetector() {
+  if (typeof navigator === "undefined") return null;
+  return navigator.language?.split("-")[0] ?? null;
+}
+function createDetectionChain(detectors) {
+  return () => {
+    for (const detector of detectors) {
+      const result = detector();
+      if (result !== null) return result;
+    }
+    return null;
+  };
+}
+
+// src/utils/interpolate.ts
+function interpolate(template, vars) {
+  if (!vars) return template;
+  return template.replace(/\{(\w+)\}/g, (_, key) => {
+    const value = vars[key];
+    return value !== void 0 ? String(value) : `{${key}}`;
+  });
+}
+
+// src/Babelize.ts
+var DEFAULT_FALLBACK_LOCALE = "en";
+var DEFAULT_API_URL2 = "https://api.babelize.co/api";
+var Babelize = class {
+  constructor() {
+    this.initialized = false;
+    this.apiKey = "";
+    this.apiUrl = DEFAULT_API_URL2;
+    this.apiClient = null;
+    this.batcher = null;
+    this._locale = DEFAULT_FALLBACK_LOCALE;
+    this.fallbackLocale = DEFAULT_FALLBACK_LOCALE;
+    this.subscribers = /* @__PURE__ */ new Set();
+    this._version = 0;
+    this.cache = new Cache();
+    this.detectLocale = createDetectionChain([browserDetector]);
+    this.batcher = new Batcher(async (locale, strings, plurals) => {
+      await this.flushBatch(locale, strings, plurals);
+    });
+  }
+  init(config) {
+    if (this.initialized) return;
+    if (typeof config === "string") {
+      config = { apiKey: config };
+    }
+    const resolved = config ?? {};
+    this.apiKey = resolved.apiKey ?? "";
+    this.apiUrl = resolved.apiUrl ?? DEFAULT_API_URL2;
+    this.fallbackLocale = resolved.fallbackLocale ?? DEFAULT_FALLBACK_LOCALE;
+    if (resolved.locale) {
+      this._locale = resolved.locale;
+    } else {
+      const detected = this.detectLocale();
+      this._locale = detected ?? this.fallbackLocale;
+    }
+    if (this.apiKey) {
+      this.apiClient = new ApiClient(this.apiKey, this.apiUrl);
+    }
+    this.initialized = true;
+  }
+  reset() {
+    this.initialized = false;
+    this.apiKey = "";
+    this.apiClient = null;
+    this.cache = new Cache();
+    this._locale = DEFAULT_FALLBACK_LOCALE;
+    this.fallbackLocale = DEFAULT_FALLBACK_LOCALE;
+    this.subscribers.clear();
+  }
+  loadLockfile(data) {
+    this.cache.loadLockfile(data);
+  }
+  t(str, vars) {
+    const cached = this.cache.get(this._locale, str);
+    if (cached !== null) {
+      return interpolate(cached, vars);
+    }
+    if (this.apiClient && this.batcher) {
+      this.batcher.add(this._locale, str);
+    }
+    return interpolate(str, vars);
+  }
+  p(singular, plural, countOrVars) {
+    let count;
+    let vars;
+    if (typeof countOrVars === "number") {
+      count = countOrVars;
+      vars = { count };
+    } else {
+      count = countOrVars.count ?? 0;
+      vars = countOrVars;
+    }
+    const rules = new Intl.PluralRules(this._locale);
+    const form = rules.select(count);
+    const key = singular;
+    const cached = this.cache.getPlural(this._locale, key, form);
+    if (cached !== null) {
+      return interpolate(cached, vars);
+    }
+    if (this.apiClient && this.batcher) {
+      this.batcher.addPlural(this._locale, key, ["one", "other"], [singular, plural]);
+    }
+    const sourceForm = form === "one" ? singular : plural;
+    return interpolate(sourceForm, vars);
+  }
+  plural(forms, vars) {
+    const count = vars?.count ?? 0;
+    const rules = new Intl.PluralRules(this._locale);
+    const form = rules.select(count);
+    const key = forms.other;
+    const cached = this.cache.getPlural(this._locale, key, form);
+    if (cached !== null) {
+      return interpolate(cached, vars);
+    }
+    if (this.apiClient && this.batcher) {
+      const entries = Object.entries(forms);
+      const formNames = entries.map(([f]) => f);
+      const templates = entries.map(([, t]) => t);
+      this.batcher.addPlural(this._locale, key, formNames, templates);
+    }
+    const sourceForm = forms[form] ?? forms.other;
+    return interpolate(sourceForm, vars);
+  }
+  tag(template) {
+    const translated = this.t(template);
+    const parts = [];
+    const markerRegex = /\{([^}]+)\}/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = markerRegex.exec(translated)) !== null) {
+      if (match.index > lastIndex) {
+        parts.push({ type: "text", value: translated.slice(lastIndex, match.index) });
+      }
+      parts.push({ type: "segment", value: match[1] });
+      lastIndex = match.index + match[0].length;
+    }
+    if (lastIndex < translated.length) {
+      parts.push({ type: "text", value: translated.slice(lastIndex) });
+    }
+    return { parts };
+  }
+  getVersion() {
+    return this._version;
+  }
+  setLocale(locale) {
+    if (locale === this._locale) return;
+    this._locale = locale;
+    this._version++;
+    this.subscribers.forEach((cb) => cb());
+  }
+  getLocale() {
+    return this._locale;
+  }
+  subscribe(cb) {
+    this.subscribers.add(cb);
+    return () => {
+      this.subscribers.delete(cb);
+    };
+  }
+  async flushBatch(locale, strings, plurals) {
+    if (!this.apiClient) return;
+    if (strings.length === 0 && !plurals?.length) return;
+    const uncached = strings.filter((s) => !this.cache.has(locale, s));
+    if (uncached.length === 0 && !plurals?.length) return;
+    try {
+      const { translations, plurals: pluralTranslations } = await this.apiClient.translate(
+        locale,
+        uncached,
+        plurals
+      );
+      let updated = false;
+      for (const [source, translation] of Object.entries(translations)) {
+        if (translation && translation !== source) {
+          this.cache.set(locale, source, translation);
+          updated = true;
+        }
+      }
+      if (pluralTranslations) {
+        for (const [canonical, forms] of Object.entries(pluralTranslations)) {
+          for (const [form, translation] of Object.entries(forms)) {
+            if (translation) {
+              this.cache.setPlural(locale, canonical, form, translation);
+              updated = true;
+            }
+          }
+        }
+      }
+      if (updated) {
+        this._version++;
+        this.subscribers.forEach((cb) => cb());
+      }
+    } catch {
+    }
+  }
+};
+
+// src/index.ts
+var _babelize = new Babelize();
+function babelize(str, vars) {
+  return _babelize.t(str, vars);
+}
+babelize.init = (config) => {
+  _babelize.init(config);
+};
+babelize.reset = () => {
+  _babelize.reset();
+};
+babelize.setLocale = (locale) => {
+  _babelize.setLocale(locale);
+};
+babelize.getLocale = () => {
+  return _babelize.getLocale();
+};
+babelize.loadLockfile = (data) => {
+  _babelize.loadLockfile(data);
+};
+babelize.subscribe = (cb) => {
+  return _babelize.subscribe(cb);
+};
+babelize.getVersion = () => {
+  return _babelize.getVersion();
+};
+babelize.tag = (template) => {
+  return _babelize.tag(template);
+};
+babelize.p = (singular, plural, countOrVars) => {
+  return _babelize.p(singular, plural, countOrVars);
+};
+babelize.plural = (forms, vars) => {
+  return _babelize.plural(forms, vars);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  babelize
+});

package/dist/index.d.cts

@@ -0,0 +1,47 @@
+interface BabelizeConfig {
+    apiKey?: string;
+    locale?: string;
+    fallbackLocale?: string;
+    apiUrl?: string;
+    storage?: TranslationStorage;
+}
+interface TranslationStorage {
+    get(locale: string, key: string): string | null;
+}
+type PluralForm = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+type PluralForms = {
+    [form in PluralForm]?: string;
+} & {
+    other: string;
+};
+interface LockfileData {
+    version: number;
+    strings: Record<string, Record<string, string>>;
+    plurals?: Record<string, {
+        forms: string[];
+        [locale: string]: Record<string, string> | string[];
+    }>;
+}
+interface TagPart {
+    type: 'text' | 'segment';
+    value: string;
+}
+interface TagResult {
+    parts: TagPart[];
+}
+
+declare function babelize(str: string, vars?: Record<string, string | number>): string;
+declare namespace babelize {
+    var init: (config?: string | BabelizeConfig) => void;
+    var reset: () => void;
+    var setLocale: (locale: string) => void;
+    var getLocale: () => string;
+    var loadLockfile: (data: LockfileData) => void;
+    var subscribe: (cb: () => void) => (() => void);
+    var getVersion: () => number;
+    var tag: (template: string) => TagResult;
+    var p: (singular: string, plural: string, countOrVars: number | Record<string, string | number>) => string;
+    var plural: (forms: PluralForms, vars?: Record<string, string | number>) => string;
+}
+
+export { type BabelizeConfig, type LockfileData, type PluralForm, type PluralForms, type TagPart, type TagResult, babelize };

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+interface BabelizeConfig {
+    apiKey?: string;
+    locale?: string;
+    fallbackLocale?: string;
+    apiUrl?: string;
+    storage?: TranslationStorage;
+}
+interface TranslationStorage {
+    get(locale: string, key: string): string | null;
+}
+type PluralForm = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other';
+type PluralForms = {
+    [form in PluralForm]?: string;
+} & {
+    other: string;
+};
+interface LockfileData {
+    version: number;
+    strings: Record<string, Record<string, string>>;
+    plurals?: Record<string, {
+        forms: string[];
+        [locale: string]: Record<string, string> | string[];
+    }>;
+}
+interface TagPart {
+    type: 'text' | 'segment';
+    value: string;
+}
+interface TagResult {
+    parts: TagPart[];
+}
+
+declare function babelize(str: string, vars?: Record<string, string | number>): string;
+declare namespace babelize {
+    var init: (config?: string | BabelizeConfig) => void;
+    var reset: () => void;
+    var setLocale: (locale: string) => void;
+    var getLocale: () => string;
+    var loadLockfile: (data: LockfileData) => void;
+    var subscribe: (cb: () => void) => (() => void);
+    var getVersion: () => number;
+    var tag: (template: string) => TagResult;
+    var p: (singular: string, plural: string, countOrVars: number | Record<string, string | number>) => string;
+    var plural: (forms: PluralForms, vars?: Record<string, string | number>) => string;
+}
+
+export { type BabelizeConfig, type LockfileData, type PluralForm, type PluralForms, type TagPart, type TagResult, babelize };

package/dist/index.js

@@ -0,0 +1,424 @@
+// src/storage/JsonStorage.ts
+var JsonStorage = class {
+  constructor() {
+    this.data = null;
+  }
+  load(data) {
+    this.data = data;
+  }
+  get(locale, key) {
+    if (!this.data) return null;
+    const translations = this.data.strings[key];
+    if (!translations) return null;
+    return translations[locale] ?? null;
+  }
+};
+
+// src/cache/Cache.ts
+var Cache = class {
+  constructor() {
+    this.memory = /* @__PURE__ */ new Map();
+    this.pluralMemory = /* @__PURE__ */ new Map();
+    this.pluralLockfile = /* @__PURE__ */ new Map();
+    this.lockfile = new JsonStorage();
+  }
+  loadLockfile(data) {
+    this.lockfile.load(data);
+    if (data.plurals) {
+      for (const [canonical, localeData] of Object.entries(data.plurals)) {
+        for (const [locale, forms] of Object.entries(localeData)) {
+          if (locale === "forms") continue;
+          const formMap = forms;
+          let localePlurals = this.pluralLockfile.get(locale);
+          if (!localePlurals) {
+            localePlurals = /* @__PURE__ */ new Map();
+            this.pluralLockfile.set(locale, localePlurals);
+          }
+          localePlurals.set(canonical, formMap);
+        }
+      }
+    }
+  }
+  get(locale, str) {
+    const localeCache = this.memory.get(locale);
+    if (localeCache?.has(str)) {
+      return localeCache.get(str);
+    }
+    const fromLockfile = this.lockfile.get(locale, str);
+    if (fromLockfile !== null) {
+      this.setMemory(locale, str, fromLockfile);
+      return fromLockfile;
+    }
+    return null;
+  }
+  set(locale, str, translation) {
+    this.setMemory(locale, str, translation);
+  }
+  getPlural(locale, key, form) {
+    const localePluralMemory = this.pluralMemory.get(locale);
+    if (localePluralMemory?.get(key)?.has(form)) {
+      return localePluralMemory.get(key).get(form);
+    }
+    const localePluralLockfile = this.pluralLockfile.get(locale);
+    if (localePluralLockfile?.has(key)) {
+      const forms = localePluralLockfile.get(key);
+      const translation = forms[form] ?? null;
+      if (translation !== null) {
+        let keyMemory = this.pluralMemory.get(locale);
+        if (!keyMemory) {
+          keyMemory = /* @__PURE__ */ new Map();
+          this.pluralMemory.set(locale, keyMemory);
+        }
+        let formMemory = keyMemory.get(key);
+        if (!formMemory) {
+          formMemory = /* @__PURE__ */ new Map();
+          keyMemory.set(key, formMemory);
+        }
+        formMemory.set(form, translation);
+        return translation;
+      }
+    }
+    return null;
+  }
+  setPlural(locale, key, form, translation) {
+    let localeMemory = this.pluralMemory.get(locale);
+    if (!localeMemory) {
+      localeMemory = /* @__PURE__ */ new Map();
+      this.pluralMemory.set(locale, localeMemory);
+    }
+    let keyMemory = localeMemory.get(key);
+    if (!keyMemory) {
+      keyMemory = /* @__PURE__ */ new Map();
+      localeMemory.set(key, keyMemory);
+    }
+    keyMemory.set(form, translation);
+  }
+  hasPlural(locale, key, form) {
+    if (this.pluralMemory.get(locale)?.get(key)?.has(form)) return true;
+    const lockfileForm = this.pluralLockfile.get(locale)?.get(key)?.[form];
+    return lockfileForm != null;
+  }
+  setMemory(locale, str, translation) {
+    let localeCache = this.memory.get(locale);
+    if (!localeCache) {
+      localeCache = /* @__PURE__ */ new Map();
+      this.memory.set(locale, localeCache);
+    }
+    localeCache.set(str, translation);
+  }
+  has(locale, str) {
+    return this.memory.get(locale)?.has(str) ?? this.lockfile.get(locale, str) !== null;
+  }
+};
+
+// src/api/client.ts
+var DEFAULT_API_URL = "https://api.babelize.co/api";
+var ApiClient = class {
+  constructor(apiKey, apiUrl = DEFAULT_API_URL) {
+    this.apiKey = apiKey;
+    this.apiUrl = apiUrl;
+  }
+  async translate(locale, strings, plurals) {
+    if (strings.length === 0 && !plurals?.length) return { translations: {} };
+    const response = await fetch(`${this.apiUrl}/v1/translate`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({ locale, strings, plurals })
+    });
+    if (!response.ok) {
+      throw new Error(`Translation API error: ${response.status}`);
+    }
+    return response.json();
+  }
+};
+
+// src/batching/Batcher.ts
+var Batcher = class {
+  constructor(flushFn) {
+    this.pending = /* @__PURE__ */ new Map();
+    this.pendingPlurals = /* @__PURE__ */ new Map();
+    this.scheduled = false;
+    this.flushFn = flushFn;
+  }
+  add(locale, str) {
+    if (!this.pending.has(locale)) {
+      this.pending.set(locale, /* @__PURE__ */ new Set());
+    }
+    this.pending.get(locale).add(str);
+    if (!this.scheduled) {
+      this.scheduled = true;
+      queueMicrotask(() => this.flush());
+    }
+  }
+  addPlural(locale, canonical, forms, templates) {
+    if (!this.pendingPlurals.has(locale)) {
+      this.pendingPlurals.set(locale, []);
+    }
+    this.pendingPlurals.get(locale).push({ canonical, forms, templates });
+    if (!this.scheduled) {
+      this.scheduled = true;
+      queueMicrotask(() => this.flush());
+    }
+  }
+  async flush() {
+    this.scheduled = false;
+    const batch = this.pending;
+    const batchPlurals = this.pendingPlurals;
+    this.pending = /* @__PURE__ */ new Map();
+    this.pendingPlurals = /* @__PURE__ */ new Map();
+    const promises = [];
+    for (const [locale, strings] of batch) {
+      const plurals = batchPlurals.get(locale);
+      if (strings.size === 0 && !plurals?.length) continue;
+      promises.push(this.flushFn(locale, [...strings], plurals));
+    }
+    for (const [locale, plurals] of batchPlurals) {
+      if (batch.has(locale)) continue;
+      if (!plurals.length) continue;
+      promises.push(this.flushFn(locale, [], plurals));
+    }
+    await Promise.all(promises);
+  }
+};
+
+// src/locale/detect.ts
+function browserDetector() {
+  if (typeof navigator === "undefined") return null;
+  return navigator.language?.split("-")[0] ?? null;
+}
+function createDetectionChain(detectors) {
+  return () => {
+    for (const detector of detectors) {
+      const result = detector();
+      if (result !== null) return result;
+    }
+    return null;
+  };
+}
+
+// src/utils/interpolate.ts
+function interpolate(template, vars) {
+  if (!vars) return template;
+  return template.replace(/\{(\w+)\}/g, (_, key) => {
+    const value = vars[key];
+    return value !== void 0 ? String(value) : `{${key}}`;
+  });
+}
+
+// src/Babelize.ts
+var DEFAULT_FALLBACK_LOCALE = "en";
+var DEFAULT_API_URL2 = "https://api.babelize.co/api";
+var Babelize = class {
+  constructor() {
+    this.initialized = false;
+    this.apiKey = "";
+    this.apiUrl = DEFAULT_API_URL2;
+    this.apiClient = null;
+    this.batcher = null;
+    this._locale = DEFAULT_FALLBACK_LOCALE;
+    this.fallbackLocale = DEFAULT_FALLBACK_LOCALE;
+    this.subscribers = /* @__PURE__ */ new Set();
+    this._version = 0;
+    this.cache = new Cache();
+    this.detectLocale = createDetectionChain([browserDetector]);
+    this.batcher = new Batcher(async (locale, strings, plurals) => {
+      await this.flushBatch(locale, strings, plurals);
+    });
+  }
+  init(config) {
+    if (this.initialized) return;
+    if (typeof config === "string") {
+      config = { apiKey: config };
+    }
+    const resolved = config ?? {};
+    this.apiKey = resolved.apiKey ?? "";
+    this.apiUrl = resolved.apiUrl ?? DEFAULT_API_URL2;
+    this.fallbackLocale = resolved.fallbackLocale ?? DEFAULT_FALLBACK_LOCALE;
+    if (resolved.locale) {
+      this._locale = resolved.locale;
+    } else {
+      const detected = this.detectLocale();
+      this._locale = detected ?? this.fallbackLocale;
+    }
+    if (this.apiKey) {
+      this.apiClient = new ApiClient(this.apiKey, this.apiUrl);
+    }
+    this.initialized = true;
+  }
+  reset() {
+    this.initialized = false;
+    this.apiKey = "";
+    this.apiClient = null;
+    this.cache = new Cache();
+    this._locale = DEFAULT_FALLBACK_LOCALE;
+    this.fallbackLocale = DEFAULT_FALLBACK_LOCALE;
+    this.subscribers.clear();
+  }
+  loadLockfile(data) {
+    this.cache.loadLockfile(data);
+  }
+  t(str, vars) {
+    const cached = this.cache.get(this._locale, str);
+    if (cached !== null) {
+      return interpolate(cached, vars);
+    }
+    if (this.apiClient && this.batcher) {
+      this.batcher.add(this._locale, str);
+    }
+    return interpolate(str, vars);
+  }
+  p(singular, plural, countOrVars) {
+    let count;
+    let vars;
+    if (typeof countOrVars === "number") {
+      count = countOrVars;
+      vars = { count };
+    } else {
+      count = countOrVars.count ?? 0;
+      vars = countOrVars;
+    }
+    const rules = new Intl.PluralRules(this._locale);
+    const form = rules.select(count);
+    const key = singular;
+    const cached = this.cache.getPlural(this._locale, key, form);
+    if (cached !== null) {
+      return interpolate(cached, vars);
+    }
+    if (this.apiClient && this.batcher) {
+      this.batcher.addPlural(this._locale, key, ["one", "other"], [singular, plural]);
+    }
+    const sourceForm = form === "one" ? singular : plural;
+    return interpolate(sourceForm, vars);
+  }
+  plural(forms, vars) {
+    const count = vars?.count ?? 0;
+    const rules = new Intl.PluralRules(this._locale);
+    const form = rules.select(count);
+    const key = forms.other;
+    const cached = this.cache.getPlural(this._locale, key, form);
+    if (cached !== null) {
+      return interpolate(cached, vars);
+    }
+    if (this.apiClient && this.batcher) {
+      const entries = Object.entries(forms);
+      const formNames = entries.map(([f]) => f);
+      const templates = entries.map(([, t]) => t);
+      this.batcher.addPlural(this._locale, key, formNames, templates);
+    }
+    const sourceForm = forms[form] ?? forms.other;
+    return interpolate(sourceForm, vars);
+  }
+  tag(template) {
+    const translated = this.t(template);
+    const parts = [];
+    const markerRegex = /\{([^}]+)\}/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = markerRegex.exec(translated)) !== null) {
+      if (match.index > lastIndex) {
+        parts.push({ type: "text", value: translated.slice(lastIndex, match.index) });
+      }
+      parts.push({ type: "segment", value: match[1] });
+      lastIndex = match.index + match[0].length;
+    }
+    if (lastIndex < translated.length) {
+      parts.push({ type: "text", value: translated.slice(lastIndex) });
+    }
+    return { parts };
+  }
+  getVersion() {
+    return this._version;
+  }
+  setLocale(locale) {
+    if (locale === this._locale) return;
+    this._locale = locale;
+    this._version++;
+    this.subscribers.forEach((cb) => cb());
+  }
+  getLocale() {
+    return this._locale;
+  }
+  subscribe(cb) {
+    this.subscribers.add(cb);
+    return () => {
+      this.subscribers.delete(cb);
+    };
+  }
+  async flushBatch(locale, strings, plurals) {
+    if (!this.apiClient) return;
+    if (strings.length === 0 && !plurals?.length) return;
+    const uncached = strings.filter((s) => !this.cache.has(locale, s));
+    if (uncached.length === 0 && !plurals?.length) return;
+    try {
+      const { translations, plurals: pluralTranslations } = await this.apiClient.translate(
+        locale,
+        uncached,
+        plurals
+      );
+      let updated = false;
+      for (const [source, translation] of Object.entries(translations)) {
+        if (translation && translation !== source) {
+          this.cache.set(locale, source, translation);
+          updated = true;
+        }
+      }
+      if (pluralTranslations) {
+        for (const [canonical, forms] of Object.entries(pluralTranslations)) {
+          for (const [form, translation] of Object.entries(forms)) {
+            if (translation) {
+              this.cache.setPlural(locale, canonical, form, translation);
+              updated = true;
+            }
+          }
+        }
+      }
+      if (updated) {
+        this._version++;
+        this.subscribers.forEach((cb) => cb());
+      }
+    } catch {
+    }
+  }
+};
+
+// src/index.ts
+var _babelize = new Babelize();
+function babelize(str, vars) {
+  return _babelize.t(str, vars);
+}
+babelize.init = (config) => {
+  _babelize.init(config);
+};
+babelize.reset = () => {
+  _babelize.reset();
+};
+babelize.setLocale = (locale) => {
+  _babelize.setLocale(locale);
+};
+babelize.getLocale = () => {
+  return _babelize.getLocale();
+};
+babelize.loadLockfile = (data) => {
+  _babelize.loadLockfile(data);
+};
+babelize.subscribe = (cb) => {
+  return _babelize.subscribe(cb);
+};
+babelize.getVersion = () => {
+  return _babelize.getVersion();
+};
+babelize.tag = (template) => {
+  return _babelize.tag(template);
+};
+babelize.p = (singular, plural, countOrVars) => {
+  return _babelize.p(singular, plural, countOrVars);
+};
+babelize.plural = (forms, vars) => {
+  return _babelize.plural(forms, vars);
+};
+export {
+  babelize
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@babelize/sdk",
+  "version": "0.0.1",
+  "description": "The simplest way to localize your app — wrap strings, Babelize handles the rest",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["babelize", "i18n", "localization", "translation", "l10n"]
+}