You have an en.json with a few hundred strings and you need de.json, fr.json and ja.json by Friday. Pasting the file into a translator looks like the fast way. It's also the fastest way to ship translated keys, broken placeholders and a file that won't parse. This guide covers four ways to translate a JSON locale file, with code you can copy, and the checks that keep each one from breaking your app.
Translate the values, never the keys. Protect placeholders ({name}, {{count}}), ICU syntax and tags before the text reaches a translator, give each target language its own plural forms, then validate the result: same keys as the source, same placeholders in every value, valid JSON. Save the file only if every check passes, and on later runs translate only the strings that changed.
If you're unsure what goes inside these files (nested keys, {name} vs {{name}}, naming), start with JSON translation files explained. This post is about getting from one language to many.
Here is a small source file:
{
"auth": {
"login": "Log in",
"welcome": "Welcome back, {name}"
},
"cart": {
"items_one": "{{count}} item",
"items_other": "{{count}} items",
"terms": "Read the <link>terms</link> before you pay."
}
}And here is what a careless translation into German produces:
{
"authentifizierung": {
"anmelden": "Anmelden",
"welcome": "Willkommen zurück, {Name}"
},
"cart": {
"items_one": "{{Anzahl}} Artikel",
"items_other": "{{count}} Artikel",
"terms": "Lesen Sie die <Link>Bedingungen</Link>, bevor Sie bezahlen.",
}
}Every line here is a real failure mode:
auth.login no longer exists in German, so the app falls back to English or shows the raw key.{Name} and {{Anzahl}} are new variables nobody passes. Users see the literal braces, or nothing.<link>, not <Link>, so the link disappears.None of these show up in a code review of the English UI. They show up in production, in a language your team may not read. So every method below follows the same rule: protect, translate, validate, then write.
Translators and reviewers rarely want raw JSON. The easy fix is to flatten the file into rows of key and value, send a spreadsheet, and rebuild the JSON from the answers:
// flatten.mjs
export function flatten(obj, prefix = "", out = {}) {
for (const [k, v] of Object.entries(obj)) {
const key = prefix ? `${prefix}.${k}` : k;
if (v && typeof v === "object" && !Array.isArray(v)) flatten(v, key, out);
else out[key] = v;
}
return out;
}
export function unflatten(flat) {
const out = {};
for (const [key, v] of Object.entries(flat)) {
const parts = key.split(".");
let node = out;
for (const part of parts.slice(0, -1)) node = node[part] ??= {};
node[parts.at(-1)] = v;
}
return out;
}
flatten turns {"auth": {"login": "Log in"}} into {"auth.login": "Log in"}, which maps to one spreadsheet row. Lock the key column so nobody edits it, add a column for context ("button on the checkout page"), and run the validation script from later in this post on whatever comes back. This approach breaks if your keys themselves contain dots, so pick a different separator if they do.
Good for: small apps, legal or marketing copy, and final review of machine output. Watch out for: it's slow, and spreadsheets go stale the moment a developer adds a key.
A translation API such as DeepL or Google Cloud Translation is fast and cheap. DeepL's free API plan, for example, covers 500,000 characters a month. The catch is that these APIs translate everything you send, including {name}. The fix is to wrap anything that must survive in a tag the API is told to ignore.
With DeepL, that's tag_handling: "xml" plus ignore_tags. Because the text is now treated as XML, the rest of it has to be escaped too:
// protect.mjs
// {{count}}, {name}, <link> / </link> / <br/>, %s and %1$s
export const TOKEN = /\{\{[^}]+\}\}|\{[\w.]+\}|<\/?[a-zA-Z][\w-]*\s*\/?>|%(?:\d+\$)?[sd]/g;
// ICU messages: {count, plural, ...} / select / selectordinal
export const ICU = /\{\s*\w+\s*,\s*(plural|select|selectordinal)\b/;
const esc = (s) => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
const unesc = (s) =>
s.replace(/</g, "<").replace(/>/g, ">").replace(/"/g, '"')
.replace(/'/g, "'").replace(/&/g, "&");
export function protect(text) {
let out = "";
let last = 0;
for (const m of text.matchAll(TOKEN)) {
out += esc(text.slice(last, m.index)) + `<x>${esc(m[0])}</x>`;
last = m.index + m[0].length;
}
return out + esc(text.slice(last));
}
export const unprotect = (text) => unesc(text.replace(/<\/?x>/g, ""));
protect("Welcome back, {name}") becomes Welcome back, <x>{name}</x>, and DeepL leaves everything inside <x> alone. Then batch the strings, since one request takes up to 50 texts:
// translate-deepl.mjs
import fs from "node:fs";
import { flatten, unflatten } from "./flatten.mjs";
import { protect, unprotect, ICU } from "./protect.mjs";
async function deepl(texts, targetLang) {
const res = await fetch("https://api-free.deepl.com/v2/translate", {
method: "POST",
headers: {
Authorization: `DeepL-Auth-Key ${process.env.DEEPL_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
text: texts,
source_lang: "EN",
target_lang: targetLang,
tag_handling: "xml",
ignore_tags: ["x"],
}),
});
if (!res.ok) throw new Error(`DeepL ${res.status}: ${await res.text()}`);
const { translations } = await res.json();
return translations.map((t) => t.text);
}
const source = flatten(JSON.parse(fs.readFileSync("locales/en.json", "utf8")));
const strings = Object.entries(source).filter(([, v]) => typeof v === "string");
const icu = strings.filter(([, v]) => ICU.test(v));
const plain = strings.filter(([, v]) => !ICU.test(v));
const target = {};
for (let i = 0; i < plain.length; i += 50) {
const batch = plain.slice(i, i + 50);
const out = await deepl(batch.map(([, v]) => protect(v)), "DE");
batch.forEach(([key], j) => (target[key] = unprotect(out[j])));
}
console.log(`Translated ${plain.length} strings. Skipped ${icu.length} ICU messages:`);
for (const [key] of icu) console.log(" " + key);
// Validate before writing (see below), then:
// fs.writeFileSync("locales/de.json", JSON.stringify(unflatten(target), null, 2) + "\n");Two things this script deliberately doesn't do:
{count, plural, one {# item} other {# items}}, the words inside the branches must be translated but the structure must not. A regex can't separate the two safely. Send those to a human, or to an LLM with the validation below.
Expect to retry: rate limits and timeouts happen on any translation API. See why translation APIs break and how to handle it for retries, Retry-After and fallbacks.
Good for: plain UI strings at volume. Watch out for: no product context ("Open" the button and "Open" the ticket status come back the same), and plurals need separate handling.
An LLM handles what the API can't: it can follow instructions about placeholders and ICU, and you can give it context. Send a JSON object of keys and values plus a short brief, and ask for the same object back:
Translate the values of this JSON object from English to German.
Rules:
- Return a JSON object with exactly the same keys. Do not translate keys.
- Keep {name}, {{count}}, <link>...</link>, %s and similar tokens exactly as written.
- In ICU messages ({count, plural, ...}), translate only the text inside the
branches and use German plural categories.
- Product: a project management app. Tone: informal, use "du".
- Keep these terms in English: Babelize, Workspace.
{"auth.login": "Log in", "auth.welcome": "Welcome back, {name}", ...}Use your provider's JSON mode or structured output so the response always parses, and send 20 to 50 keys per request so one bad response doesn't cost you the whole file. Glossary terms and a line about the product do more for quality than any choice of model.
Then assume the model made mistakes, because sometimes it will: a dropped placeholder, an English value handed back, or a key it invented. Which brings us to the step that matters for every method.
Good for: UI copy with context, ICU messages, tone. Watch out for: confident mistakes, so never write its output without the checks below.
Whatever produced the translation, a person, an API or a model, run the same checks on it. This one compares the target to the source key by key:
// validate.mjs
import { parse } from "@formatjs/icu-messageformat-parser";
import { TOKEN, ICU } from "./protect.mjs";
const tokens = (s) => (s.match(TOKEN) ?? []).sort().join("|");
export function validate(source, target) {
const problems = [];
const warnings = [];
for (const [key, src] of Object.entries(source)) {
if (typeof src !== "string") continue;
const t = target[key];
if (t === undefined) { problems.push(`${key}: missing`); continue; }
if (typeof t !== "string" || t.trim() === "") problems.push(`${key}: empty`);
else if (tokens(src) !== tokens(t)) problems.push(`${key}: placeholders or tags changed`);
else if (t === src && /[a-z]{4}/i.test(src)) warnings.push(`${key}: identical to source`);
if (ICU.test(src)) {
try { parse(t); } catch { problems.push(`${key}: invalid ICU message`); }
}
}
for (const key of Object.keys(target)) {
if (!(key in source)) problems.push(`${key}: not in the source file`);
}
return { problems, warnings };
}"Identical to source" is a warning rather than an error: brand names, codes and words like "OK" legitimately stay the same. Everything else should stop the write. Leave failed keys out of the file instead of filling them with English, so the fallback is visible and the next run can retry them:
const { problems, warnings } = validate(source, target);
if (warnings.length) console.warn(warnings.join("\n"));
const failed = new Set(problems.map((p) => p.split(":")[0]));
const clean = Object.fromEntries(Object.entries(target).filter(([k]) => !failed.has(k)));
const json = JSON.stringify(unflatten(clean), null, 2) + "\n";
fs.writeFileSync("locales/de.json.tmp", json);
fs.renameSync("locales/de.json.tmp", "locales/de.json"); // never a half-written file
if (problems.length) {
console.error(problems.join("\n"));
process.exitCode = 1;
}
Writing to a temporary file and renaming it means a crash halfway through can't leave a truncated de.json behind. Run the same validate() in CI on every locale file, so a hand edit with a missing brace fails the build instead of the release.
This is the mistake that passes every check above. English has two plural forms. Many languages have more:
new Intl.PluralRules("en").resolvedOptions().pluralCategories; // one, other
new Intl.PluralRules("pl").resolvedOptions().pluralCategories; // one, few, many, other
new Intl.PluralRules("ar").resolvedOptions().pluralCategories; // zero, one, two, few, many, other
new Intl.PluralRules("ja").resolvedOptions().pluralCategories; // other
With i18next, plural forms are separate keys: items_one and items_other in English. A Polish file translated one to one has only those two, so Polish users never see the forms for "2 items" or "5 items". The Polish file needs its own keys:
{
"items_one": "{{count}} przedmiot",
"items_few": "{{count}} przedmioty",
"items_many": "{{count}} przedmiotów",
"items_other": "{{count}} przedmiotu"
}
So when the target language has categories the source doesn't, generate the extra keys from Intl.PluralRules and ask for each form. With ICU messages it's the same idea inside one string: the Polish message needs one, few, many and other branches. For Japanese, the opposite: one _other key covers every count. The ICU MessageFormat plurals guide covers the syntax in detail.
Translating the whole file on every release wastes money and quietly replaces translations someone already reviewed. Instead, record a hash of each source string when you translate it, and on the next run only send keys whose hash changed or that the target file doesn't have yet:
import crypto from "node:crypto";
const hash = (s) => crypto.createHash("sha256").update(s).digest("hex").slice(0, 16);
const lockPath = "locales/.translate-lock.json";
const lock = fs.existsSync(lockPath) ? JSON.parse(fs.readFileSync(lockPath, "utf8")) : {};
lock.de ??= {};
const existing = flatten(JSON.parse(fs.readFileSync("locales/de.json", "utf8")));
const todo = Object.entries(source).filter(
([key, value]) => typeof value === "string" && (lock.de[key] !== hash(value) || !(key in existing)),
);
// translate `todo`, merge into `existing`, validate, write, then:
for (const [key, value] of todo) if (!failed.has(key)) lock.de[key] = hash(value);
fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n");Commit the lock file next to your locale files. A teammate who fixes a typo in the English text then triggers a retranslation of exactly that one string, and everyone else's run costs nothing.
| Method | Best for | Cost | Main risk |
|---|---|---|---|
| Pasting into a translator or online JSON tool | A one-off look at a tiny file | Free | Translated keys, broken placeholders, your strings on a third-party site |
| Human translators via spreadsheet | Legal, marketing, final review | Highest | Slow, goes stale quickly |
| Translation API script | Plain UI strings at volume | Low | No context, ICU and plurals need extra work |
| LLM script with validation | UI copy with context, ICU | Low | Confident mistakes if you skip validation |
| Translation management system (Crowdin, Lokalise, Phrase) | Teams with translators and many locales | Monthly per seat or key | Setup and sync between the platform and your repo |
For a team of developers without dedicated translators, a script built on an LLM or a translation API plus validation gets you most of the way. For a deeper look at the platform options, see Lokalise and Crowdin alternatives for developers.
Everything above is what Babelize (our product) does when you run it in a repo. In a React, Next.js or static HTML project (Vue and React Native are in beta), one command reads your source locale file, keeps your existing keys and translations, and translates the rest:
npx babelize translate --to de,fr,ja
git diff{name}, {{count}} and %s, tags and brand names are swapped for opaque tokens before translation.
It also does the step before all of this: if your strings are still hardcoded in components, it extracts them into the JSON file first. Use your own Anthropic, OpenAI, Gemini, Groq or OpenRouter key and you don't need an account. The limits, to be fair: it works on a git repo in one of those frameworks, not on a standalone JSON file, and it writes JSON and gettext .po files only (no YAML, XLIFF or mobile string files). The translate command docs list every flag.
Translating locale files for a mobile app? The React Native i18n guide shows how to bundle them with an Expo app and pick the device language.