Core Runtime

@babelize/sdk is the foundation of the Babelize SDK. It provides the translation function, caching, locale management, and batch API communication.

Initialization

Initialize the SDK with your API key:

import { babelize } from "@babelize/sdk";

babelize.init("bblz_sk_xxxxxxxxx");

Or with a config object:

babelize.init({
  apiKey: "bblz_sk_xxxxxxxxx",
  locale: "ja",
  fallbackLocale: "en",
  apiUrl: "https://api.babelize.co/api",
});

The API key is optional in production. Without a key, the SDK uses the lockfile only and never makes API calls.

Translating Strings

Wrap any string with babelize():

babelize("Welcome");                         // "ようこそ"
babelize("Hello {name}", { name: "Mohit" });  // "こんにちは Mohit"
babelize("You have {count} messages", { count: 5 }); // "5件のメッセージがあります"

{key} placeholders are interpolated with the provided variables. The translation happens automatically — the SDK checks memory cache first, then the lockfile, then falls back to the API.

Locale Management

Set and get the active locale:

babelize.setLocale("fr");
const current = babelize.getLocale(); // "fr"

Locale is auto-detected from the browser (navigator.language) when not specified. All subsequent babelize() calls use the active locale.

Loading the Lockfile

In production, translations are pre-built into a lockfile. Load it at startup:

import lockfile from "virtual:babelize-lockfile";

lockfile && babelize.loadLockfile(lockfile);

The lockfile is generated by the build plugin (@babelize/vite or @babelize/next). Once loaded, all translations are served from it with zero API calls.

Cache Strategy

The SDK uses a multi-tier cache for maximum performance:

Memory Cache      < 0.1ms    — fastest, cleared on page reload
    ↓ (miss)
Lockfile Cache    < 1ms      — loaded from build-time lockfile
    ↓ (miss)
Babelize API      < 100ms    — fetched and cached for subsequent calls
    ↓ (miss)
Original string              — fallback, never fails

When the API returns a translation, it's stored in memory cache so subsequent calls for the same string are instant.

Multiple babelize() calls within the same render cycle are automatically batched into a single API request. The SDK collects all missing strings and sends them together, reducing latency and API usage.

// These three calls are batched into one API request
<h1>{babelize("Welcome")}</h1>
<p>{babelize("Get Started")}</p>
<button>{babelize("Learn More")}</button>

Lockfile Format

The lockfile stores all pre-translated strings per locale:

{
  "version": 1,
  "meta": {
    "generatedAt": "2026-07-30T12:00:00Z",
    "locales": ["ja", "fr", "de"],
    "totalStrings": 42
  },
  "strings": {
    "Welcome": {
      "ja": "ようこそ",
      "fr": "Bienvenue",
      "de": "Willkommen"
    },
    "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" }
    }
  }
}

Reactivity

Subscribe to state changes for custom reactivity:

const unsubscribe = babelize.subscribe(() => {
  console.log("Locale or cache updated");
});

// Later, clean up
unsubscribe();

babelize.getVersion() returns a number that increments on every state change. This is used internally by the React bindings to trigger re-renders via useSyncExternalStore.

Testing

Reset all state between tests:

babelize.reset();

This clears the cache, locale, subscribers, and API client — giving you a clean slate for each test case.

TypeScript

import type { BabelizeConfig, LockfileData, PluralForms, TagResult } 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;
};