Most i18n setups start the same way: invent a key like home.hero.title, move the English text into en.json, replace it with t("home.hero.title"), and repeat for every string in the app. The Babelize SDK skips that step. You wrap the English text where it already is, and a build plugin finds it, translates it and writes a lockfile your app reads at runtime. This post shows how it works in React, Next.js and React Native, and where the trade-offs are.
Install @babelize/sdk and the build plugin for your bundler (@babelize/next, @babelize/vite or @babelize/metro). Wrap text with babelize("Welcome back"), or useBabelize() in React components. On build, the plugin scans for those calls, translates every string into your target locales through the Babelize API, and writes babelize-lock.json. The app loads the lockfile and reads translations from it, so production makes no translation API calls and your API key never reaches the browser.
There are two ways to identify a message in i18n. Key-based libraries such as react-i18next and next-intl use an ID you choose:
// en.json
{ "home": { "welcome": "Welcome back, {{name}}" } }
// Home.tsx
<h1>{t("home.welcome", { name })}</h1>
Source-string libraries use the English text itself as the ID. GNU gettext has worked this way for decades (Django's gettext("Welcome back") is an example), and Lingui's macros do it in React. The Babelize SDK takes the same approach:
// Home.tsx
<h1>{babelize("Welcome back, {name}", { name })}</h1>The benefit is that the component stays readable and there is no second file to keep in sync while you build. The cost is that changing the English text changes the ID, so the new text needs translating again. For a product team that edits copy often, that is usually what you want anyway; for a large app with professional translators, keys give more control. We cover the key-based side in JSON translation files explained.
babelize("..."), babelize.p(...) for plurals, or the <BabelizeTag> component for sentences with markup.BABELIZE_API_KEY at build time only.babelize-lock.json maps each source string to its translations. Commit it.The lockfile is plain JSON:
{
"version": 1,
"strings": {
"Welcome back, {name}": {
"fr": "Bon retour, {name}",
"de": "Willkommen zurück, {name}",
"ja": "おかえりなさい、{name}さん"
}
}
}Install the SDK and the Vite plugin:
npm install @babelize/sdk
npm install -D @babelize/viteAdd the plugin with the languages you want:
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import babelize from "@babelize/vite";
export default defineConfig({
plugins: [react(), babelize({ locales: ["fr", "de", "ja"] })],
});
Put BABELIZE_API_KEY in .env, without a VITE_ prefix: the plugin reads it at build time, and a VITE_ variable would be bundled into the browser code. Then load the lockfile and wrap your app:
// src/main.tsx
import { createRoot } from "react-dom/client";
import { babelize } from "@babelize/sdk";
import { BabelizeProvider } from "@babelize/sdk/react";
import lockfile from "virtual:babelize-lockfile";
import { App } from "./App";
lockfile && babelize.loadLockfile(lockfile);
babelize.init(); // no API key in browser code
createRoot(document.getElementById("root")!).render(
<BabelizeProvider>
<App />
</BabelizeProvider>,
);TypeScript doesn't know the virtual module, so declare it once:
// src/babelize.d.ts
declare module "virtual:babelize-lockfile" {
import type { LockfileData } from "@babelize/sdk";
const lockfile: LockfileData | null;
export default lockfile;
}In components, use the hook. Name its result babelize: the build plugin finds strings by looking for babelize("...") calls, so a hook result called t would be skipped.
import { useBabelize, useLocale } from "@babelize/sdk/react";
export function Header({ name, unread }: { name: string; unread: number }) {
const babelize = useBabelize();
const { locale, setLocale } = useLocale();
return (
<header>
<h1>{babelize("Welcome back, {name}", { name })}</h1>
<p>{babelize.p("{count} new message", "{count} new messages", unread)}</p>
<select value={locale} onChange={(e) => setLocale(e.target.value)}>
<option value="en">English</option>
<option value="fr">Français</option>
<option value="ja">日本語</option>
</select>
</header>
);
}
setLocale re-renders every component that uses the hook. Without it, the SDK picks the browser's language and falls back to English.
Wrap your Next.js config:
// next.config.ts
import withBabelize from "@babelize/next";
export default withBabelize({}, { locales: ["fr", "de", "ja"] });
The plugin runs while Next.js loads the config, before Turbopack or webpack starts, so the lockfile is ready before the bundle is built. It runs on next build and once when next dev starts. If any locale fails to translate, the build fails rather than shipping a partial lockfile.
For Server Components, add the middleware that picks the locale from a cookie or the Accept-Language header:
// proxy.ts (middleware.ts before Next.js 16)
import { babelizeMiddleware } from "@babelize/sdk/next";
export default babelizeMiddleware({ supportedLocales: ["en", "fr", "de", "ja"] });Then translate on the server:
// app/page.tsx
import { babelizeRSC, loadLockfile } from "@babelize/sdk/next";
import lockfile from "../babelize-lock.json";
loadLockfile(lockfile);
export default async function Home() {
return <h1>{await babelizeRSC("Welcome to our store")}</h1>;
}
Client Components use the same useBabelize() hook as in the Vite example. The Next.js SDK docs cover the full setup.
The Metro plugin writes the lockfile before Metro bundles, for expo start, expo export and the React Native CLI:
// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const { withBabelize } = require("@babelize/metro");
module.exports = withBabelize(getDefaultConfig(__dirname), {
locales: ["fr", "de", "ja"],
});// App.tsx
import { getLocales } from "expo-localization";
import { babelize } from "@babelize/sdk";
import lockfile from "./babelize-lock.json";
babelize.loadLockfile(lockfile);
babelize.init({ detectLocale: () => getLocales()[0]?.languageCode ?? null });
Render translations inside <Text> as usual. Never pass an API key in a mobile app; anything in the bundle can be extracted. The React Native SDK docs have the details.
babelize.p(singular, plural, count) takes the two English forms and returns the right form for the current language using Intl.PluralRules, including the extra forms in Polish, Russian or Arabic.babelize.plural({ one, few, many, other }, { count }) gives full control over all six CLDR plural forms.babelize.icu("{count, plural, one {# item} other {# items}}", { count }) accepts ICU MessageFormat and translates the text inside it while keeping the structure. See our ICU MessageFormat guide for the syntax.<BabelizeTag> translates a sentence that contains markup as one unit, so the translator can reorder it for languages like Japanese:<BabelizeTag
template="Read our {terms} before you {sign up}"
segments={{
terms: <a href="/terms">terms</a>,
"sign up": <strong>sign up</strong>,
}}
/>The SDK is new (version 0.1), so here is where it fits and where it doesn't yet:
babelize-lock.json avoids surprises. The Next.js and Metro plugins write it before bundling and don't have this issue.babelize("...") calls. A string built at runtime, like babelize(`Status: ${code}`), can't be found, and neither can a call under another name unless you set the plugin's functionName option.
Babelize also has a CLI that takes the opposite approach: npx babelize translate finds hardcoded strings, wraps them in react-i18next, next-intl or Django gettext calls, and writes standard locale files to your repo. The two suit different projects:
| SDK | CLI | |
|---|---|---|
| What you write | babelize("Welcome back") | Nothing; it rewrites to t("home.welcomeBack") |
| Translations live in | babelize-lock.json | Standard JSON or .po locale files |
| Runtime library | @babelize/sdk | react-i18next, next-intl or gettext |
| Translates | On every build | When you run it, or in a pull request |
| Best for | New apps, prototypes, small teams | Existing apps, teams that want standard libraries |
If you would rather pick a standard library, our best i18n libraries for 2027 post picks one per framework, and the CLI can do the first wrapping pass for it.
--- - [All articles](https://www.babelize.co/blogs)