SDK Overview

The Babelize SDK is the simplest way to localize any JavaScript application. Instead of maintaining translation keys, locale JSON files, and complex i18n configurations, you simply wrap any string with babelize() and the SDK handles everything else.

import { babelize } from "@babelize/sdk";
import lockfile from "virtual:babelize-lockfile"; // generated at build time

lockfile && babelize.loadLockfile(lockfile);
babelize.init(); // no API key in browser code

<h1>{babelize("Welcome")}</h1>
<p>{babelize("Hello {name}", { name: user.name })}</p>

How It Works

The SDK operates in two modes:

Build time — A plugin (@babelize/vite, @babelize/next or @babelize/metro) scans your source code for babelize() calls, extracts all strings, and sends them to the Babelize API for translation. The translations are saved in babelize-lock.json.

Runtime — When your app runs, the SDK loads the lockfile and uses it for instant translations. In the browser that is all it does: a string missing from the lockfile is shown unchanged. Only server-side code that passes an API key to babelize.init() fetches missing strings from the API, in the background, and re-renders when the translation arrives.

Build Time:
  Scan source → Extract strings → API translates → babelize-lock.json

Runtime (browser, no key):
  babelize("Welcome") → check cache → check lockfile → instant translation (or the original string)

Runtime (server, with an API key):
  babelize("Welcome") → check cache → check lockfile → API fallback → re-render

Packages

SDK vs CLI

The CLI (npx babelize) is designed for translating your entire project in one go — it finds hardcoded text, wraps it in your framework's i18n calls, translates it, and writes locale files into your repo for review with git diff. Run it locally or in CI.

The SDK is designed for runtime translation within your application — strings are translated on the fly, cached locally, and served without any additional developer effort. You don't manage locale files, run commands, or configure projects.

Use the SDK when you want localization to feel like using JavaScript. Use the CLI when you need full control over the translation pipeline.