BLOG
i18n Without Translation Keys: Meet the Babelize SDK
TL;DR: Install @babelize/sdk and the build plugin for your bundler (@babelize/next, @babelize/vite or @babelize/metro), then wrap text with babelize("Welcome back") or the useBabelize() hook. On build, the plugin finds those strings, translates them through the Babelize API and writes babelize-lock.json. The app reads translations from the lockfile, so production makes no translation API calls and the API key never reaches the browser.
Key Takeaways
- Source-string i18n uses the English text as the message ID, like gettext and Lingui, so there are no keys to invent
- Build plugins for Next.js, Vite and Metro scan, translate and write a lockfile; the API key is used at build time only
- Plurals use Intl.PluralRules, ICU messages are supported, and <BabelizeTag> keeps sentences with markup in one unit
- Trade-offs: identical English text shares one translation, edited copy is retranslated, and the Vite lockfile lands one build late
- For standard locale files and libraries like react-i18next or next-intl, use the Babelize CLI instead
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.
Quick Answer
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.
Keys vs Source Strings
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.
How the SDK Works
- You wrap strings.
babelize("..."),babelize.p(...)for plurals, or the<BabelizeTag>component for sentences with markup. - The build plugin scans. It parses your source files and collects every wrapped string and plural template.
- It translates. Each string is translated into the locales you configured, using your
BABELIZE_API_KEYat build time only. - It writes a lockfile.
babelize-lock.jsonmaps each source string to its translations. Commit it. - The app reads the lockfile. At runtime, a lookup is an in-memory read. A string missing from the lockfile is shown in English instead of breaking the page.
The lockfile is plain JSON:
{
"version": 1,
"strings": {
"Welcome back, {name}": {
"fr": "Bon retour, {name}",
"de": "Willkommen zurück, {name}",
"ja": "おかえりなさい、{name}さん"
}
}
}
React with Vite
Install the SDK and the Vite plugin:
npm install @babelize/sdk
npm install -D @babelize/vite
Add 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.
Next.js App Router
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.
React Native and Expo
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.
Plurals, ICU and Rich Text
babelize.p(singular, plural, count)takes the two English forms and returns the right form for the current language usingIntl.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>,
}}
/>
Trade-offs to Know
The SDK is new (version 0.1), so here is where it fits and where it doesn't yet:
- Same text, different meaning. Because the English text is the ID, "Close" on a button and "Close" meaning "nearby" share one translation. Key-based libraries, or gettext's contexts, handle that better.
- Editing copy means retranslating. Changing "Sign up" to "Create account" is a new string. The next build translates it, which uses credits.
- Vite writes the lockfile one build late. The Vite plugin writes the lockfile after the bundle is emitted, so a fresh checkout needs a second build, and new strings appear one build later. Committing
babelize-lock.jsonavoids surprises. The Next.js and Metro plugins write it before bundling and don't have this issue. - Scanning is static. The plugins find literal strings in
babelize("...")calls. A string built at runtime, likebabelize(`Status: ${code}`), can't be found, and neither can a call under another name unless you set the plugin'sfunctionNameoption. - No translator workspace. Translations come from the Babelize API. If you work with human translators and a TMS, a key-based library with locale files is the better fit.
SDK or CLI?
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.

Mohit Sapat
Founder of Babelize
Mohit is building Babelize because shipping your app in another language shouldn't cost a sprint of spreadsheets and JSON files. He's a builder first: he ships product, talks to users every week and turns what he hears into the next release. Babelize is bootstrapped, so he also runs the business, writes the blog and shoots the reels. He's been featured in magazines, but he'd rather show you the changelog.


