A JSON translation file is where your app's words live. Learn how JSON locale files are structured, how the t() function finds the right string, how to name and organize files per language, how to translate a JSON file without breaking it, and the mistakes that cause missing text in production.
A JSON translation file (also called a JSON locale file or JSON language file) stores the user-facing text of your application for one language. Instead of writing text directly inside your components, you give every string a key and put the actual words in a file per language. At runtime, your i18n library loads the file for the active locale and looks up each key.
Think of it like a dictionary:
{
"welcome": "Welcome",
"login": "Log in",
"logout": "Log out",
"profile": "Profile"
}
Here, welcome, login, logout, and profile are translation keys. The values are the text users see. A French file has the exact same keys with French values, and a German file has the same keys with German values. That is the whole contract of a multi-language JSON setup: keys are identical across every locale, only the values change.
JSON became the default format for web localization because every JavaScript runtime can parse it natively, bundlers can import it directly, and it maps cleanly to the nested objects that libraries like next-intl, react-i18next, vue-i18n, and FormatJS expect.
On a small project, writing text directly inside your components feels normal. The moment someone asks to support French, then German, then Japanese, every hardcoded string becomes a file you have to edit, a review you have to repeat, and a place a translation can be forgotten.
Instead, your component asks for a key:
<h1>{t("welcome")}</h1>Now the component does not care which language the user speaks. The translation file does the rest. This separation is the core of internationalization; if the distinction between preparing code and adapting content is new to you, our explainer on i18n vs l10n covers it in detail.
There are two common ways to shape a JSON translation file. A flat file uses one level of keys, usually with dots in the key name:
{
"auth.login.title": "Sign in to your account",
"auth.login.button": "Log in",
"auth.logout": "Log out"
}A nested file groups related strings into objects:
{
"auth": {
"login": {
"title": "Sign in to your account",
"button": "Log in"
},
"logout": "Log out"
}
}
In most libraries you read both shapes the same way, with dot notation: t("auth.login.button"). Nested files are easier to scan and let you pass a whole group to one component. next-intl, for example, expects nested messages and lets you scope a hook to a branch with useTranslations("auth.login"), then call t("button"). Flat files are easier to grep and diff line by line, and some translation tools prefer them. Pick one shape per project and stick with it; mixing them leads to keys that resolve in one locale and not another.
Whichever shape you choose, name keys by meaning and location, not by content. checkout.payButton survives a copy change from "Pay now" to "Complete purchase". A key called payNow does not, and a key called text1 tells nobody anything.
Name each file after a BCP 47 language tag: en.json, fr.json, de.json, ja.json, and add a region only when content actually differs, as in pt-BR.json and pt-PT.json. Use hyphens rather than underscores, since the JavaScript Intl API and HTML lang attributes expect hyphenated tags. Our guide to locale codes and BCP 47 covers the traps, such as Japanese being ja, not jp.
A single file per locale is fine for small apps. As the app grows, split each locale into a folder of namespaces, one per feature:
locales/
├── en/
│ ├── common.json
│ ├── auth.json
│ └── billing.json
├── fr/
│ ├── common.json
│ ├── auth.json
│ └── billing.json
└── pt-BR/
├── common.json
├── auth.json
└── billing.jsonNamespaces keep files small enough to review, reduce merge conflicts when several people add strings at once, and let a library load only the namespaces a page needs instead of every string in the app.
The t() function (short for "translate") does not translate anything. It is a lookup. Given a key, it resolves the value in the active locale's messages, fills in any variables, and returns a string. Here is a minimal version in plain JavaScript that shows the moving parts:
const messages = {
en: { cart: { title: "Your cart", greeting: "Hi {name}!" } },
fr: { cart: { title: "Votre panier" } },
};
function t(locale, key, values = {}) {
const lookup = (loc) => key.split(".").reduce((node, part) => node?.[part], messages[loc]);
const template = lookup(locale) ?? lookup("en") ?? key;
return template.replace(/\{(\w+)\}/g, (_, name) => values[name] ?? `{${name}}`);
}
t("fr", "cart.title"); // "Votre panier"
t("fr", "cart.greeting", { name: "Léa" }); // "Hi Léa!" (fell back to English)
t("fr", "cart.total"); // "cart.total" (missing everywhere)Real libraries add caching, plural rules, and formatting, but follow the same three steps:
fallbackLng chain (for example pt-BR -> pt -> en). next-intl reports the missing message through its onError handler and renders a fallback, by default the key path.
That fallback behavior is why a missing key rarely crashes your app. Instead, a French user quietly sees English, or worse, sees cart.total on screen. Treat missing keys as bugs and catch them before users do: our guide to automating app localization includes a short Node.js script that fails CI when a locale is missing keys.
Variables are where JSON translation files stop being interchangeable between libraries. The two dominant syntaxes look almost identical:
// ICU syntax: next-intl, react-intl / FormatJS, vue-i18n
"greeting": "Welcome back, {name}!"
// i18next default syntax: i18next, react-i18next
"greeting": "Welcome back, {{name}}!"
Both are called the same way, t("greeting", { name: user.firstName }), but a file written for one library will print literal braces in the other. If you migrate between libraries, convert placeholders as part of the move.
Always use placeholders rather than concatenating fragments. t("hello") + " " + name forces English word order on every language. A single message with {name} lets the translator put the name wherever the grammar needs it.
Plurals are the other big syntax split. ICU-based libraries keep every plural form inside one message:
{
"itemCount": "{count, plural, =0 {Your cart is empty} one {# item} other {# items}}"
}i18next (v21 and later) uses separate keys with a plural-category suffix, and picks one based on the count you pass:
{
"itemCount_zero": "Your cart is empty",
"itemCount_one": "{{count}} item",
"itemCount_other": "{{count}} items"
}
Either way, the set of plural forms belongs to each language, not to English. Polish needs one, few, many, and other; Japanese needs only other. A Polish i18next file therefore has keys like itemCount_few that the English file does not. Our ICU MessageFormat plurals guide explains the categories and why a count === 1 check breaks in most languages.
next-intl loads one messages file per locale on the server, in the request config. Only the locale being rendered is imported:
// src/i18n/request.ts
import { getRequestConfig } from "next-intl/server";
import { hasLocale } from "next-intl";
import { routing } from "./routing";
export default getRequestConfig(async ({ requestLocale }) => {
const requested = await requestLocale;
const locale = hasLocale(routing.locales, requested) ? requested : routing.defaultLocale;
return {
locale,
messages: (await import(`../../messages/${locale}.json`)).default,
};
});
Server Components then call getTranslations() and Client Components call useTranslations(). The full setup is in our step-by-step next-intl tutorial.
react-i18next takes resources organized by language and namespace. You can bundle them directly, or lazy-load them over HTTP with a backend plugin such as i18next-http-backend:
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import enCommon from "./locales/en/common.json";
import frCommon from "./locales/fr/common.json";
i18n.use(initReactI18next).init({
resources: {
en: { common: enCommon },
fr: { common: frCommon },
},
lng: "en",
fallbackLng: "en",
defaultNS: "common",
interpolation: { escapeValue: false }, // React already escapes output
});
Components use const { t } = useTranslation("common"). If you are still choosing between the two libraries, see our next-intl vs react-i18next comparison.
Translating a JSON file looks like a simple find-and-replace job. It is the step where most localization bugs are introduced, because a translator or a machine translation tool that does not understand the file's rules can break it in ways that only show up at runtime.
"login": "Connexion" is right. "connexion": "Connexion" means the French build can no longer find login.{name} and {{count}} must survive untouched. A translated {nom} renders as a literal or throws.plural, select, one, and other are code, not English. Only the text inside the branches gets translated.<link>Terms</link>, the tag names must stay the same so your component can map them.\". Accented and non-Latin characters can be stored directly in UTF-8; there is no need for \u escapes.Generic machine translation, including pasting a whole file into a chatbot, tends to fail on exactly these points: it translates keys, rewrites placeholders, "fixes" ICU keywords, or returns a file with a trailing comma. It also lacks context; "Open" as a button and "Open" as a ticket status translate differently in many languages. Whatever tool you use, run the same automated checks on its output that you would run on a human translator's.
JSON dominates web projects, but it is not the only format. You will meet these as soon as you add a mobile app or work with a translation agency:
| Format | Typical use | Notes |
|---|---|---|
| JSON | JavaScript web apps (next-intl, i18next, vue-i18n) | Native to JS, supports nesting, no comments |
| YAML | Ruby on Rails, some static site generators | Allows comments, indentation-sensitive |
| PO / gettext | Django, PHP, Linux and C projects | Source text as the key, translator comments, built-in plural forms |
| XLIFF | Exchange with translation agencies and CAT tools | XML standard holding source and target side by side |
| ARB | Flutter | JSON-based, ICU messages, metadata in @key entries |
.strings / .xcstrings |
iOS and macOS | Apple's string catalogs; .xcstrings is JSON-based |
strings.xml |
Android | XML resources with a dedicated plurals element |
One limitation stands out: JSON has no comments, so there is nowhere to tell a translator that "Save" is a verb on a button and not a noun. Teams work around this with a separate description file, a context field in their translation platform, or descriptive key names. If you are standardizing on JSON, see how Babelize handles JSON locale files.
en.json but not to de.json silently falls back to English. A key renamed in one file but not the others is the same bug in reverse.JSON.parse does not complain about them; the last value wins, so an earlier translation silently disappears.JSON.parse throw, and non-UTF-8 encodings turn accents into garbage.
Key drift is easy to detect automatically. This Node script flattens every locale file and compares its keys against en.json, failing the build if any are missing or extra:
// scripts/check-locales.mjs
import fs from "node:fs";
import path from "node:path";
const dir = "messages";
const flatten = (obj, prefix = "") =>
Object.entries(obj).flatMap(([key, value]) =>
value && typeof value === "object" ? flatten(value, `${prefix}${key}.`) : [`${prefix}${key}`]
);
const keysOf = (file) => new Set(flatten(JSON.parse(fs.readFileSync(path.join(dir, file), "utf8"))));
const source = keysOf("en.json");
let failed = false;
for (const file of fs.readdirSync(dir).filter((f) => f.endsWith(".json") && f !== "en.json")) {
const keys = keysOf(file);
const missing = [...source].filter((k) => !keys.has(k));
const extra = [...keys].filter((k) => !source.has(k));
if (missing.length || extra.length) {
failed = true;
console.error(`${file}: missing [${missing.join(", ")}] extra [${extra.join(", ")}]`);
}
}
process.exit(failed ? 1 : 0);
Because JSON.parse runs on every file, the script also fails on invalid JSON. If you use i18next plural suffixes, strip _zero, _one, _two, _few, _many, and _other before comparing, since each language legitimately has a different set. To catch strings that never made it into a JSON file at all, pair this with pseudo-localization testing.
With TypeScript, you can make a typo in a key a compile error instead of a blank label. Both major libraries type keys from your source-language JSON file through module augmentation. In next-intl:
// global.d.ts
import messages from "./messages/en.json";
declare module "next-intl" {
interface AppConfig {
Messages: typeof messages;
}
}And in react-i18next:
// i18next.d.ts
import "i18next";
import common from "./locales/en/common.json";
declare module "i18next" {
interface CustomTypeOptions {
defaultNS: "common";
resources: { common: typeof common };
}
}
With either in place, t("auth.logn") fails type checking and your editor autocompletes valid keys.
A JSON translation file stores an application's user-facing text for one language as key-value pairs, for example en.json for English and fr.json for French. The code references keys, and the i18n library loads the file for the active locale and returns the matching value.
Name each file after a BCP 47 language tag, such as en.json, fr.json, or pt-BR.json, using hyphens rather than underscores. Add a region only when content differs between regions. For larger apps, use one folder per locale with a JSON file per feature namespace.
Both work, and most libraries read either shape with dot notation such as auth.login.button. Nested files are easier to scan and let you scope translations to a component; flat files are easier to search and diff. Choose one shape per project and use it consistently.
Translate only the values, never the keys. Keep placeholders such as {name} or {{count}}, ICU keywords like plural and other, and rich-text tags exactly as they are. Save the file as UTF-8, escape double quotes, and parse every file in CI to catch invalid JSON.
Most libraries fall back instead of crashing. i18next tries the fallback language chain and then shows the key itself. next-intl reports the error and renders a fallback, by default the key path. Users see English or a raw key, so check for missing keys in CI.
JSON translation files look simple, and that is their strength: one file per locale, identical keys, values that change. The work is in keeping them that way. Use meaningful nested keys, BCP 47 file names, placeholders instead of concatenation, and real plural syntax. Translate values only, validate every file, and fail the build when locales drift apart.
Keeping ten locale files in sync by hand is the part that does not scale. Babelize detects new and changed keys in your source JSON, generates placeholder-safe translations for every locale, and commits them back to your repository. You can run it from the terminal with the Babelize CLI.
--- - [All articles](https://www.babelize.co/blogs)