To translate a JSON file, you translate the text values and leave everything else alone: the keys, the brackets, the numbers and the placeholders your code fills in. Then you save the result as a new file for the target language, usually named after it, such as de.json. This guide covers what’s inside a JSON language file, the mistakes that break one, and the fastest way to get it translated.
What Is a JSON Language File?
JSON is a plain-text format that apps and websites use to store data, and many of them keep their interface text in it, one file per language. Plenty of React and Vue apps do this, and so do many mobile apps and games. A language file pairs a key the code looks up with the text people see:
{
"checkout": {
"title": "Your cart",
"empty": "Your cart is empty",
"greeting": "Hi, {name}!"
},
"itemCount": 3
}
checkout, title, empty and greeting are keys. The code asks for checkout.title, so a key must never change. The text after each colon is the value, and that’s the part a translator works on. {name} is a placeholder the app replaces with a real name when the page is shown.
How to Translate a JSON File, Step by Step
- Copy the source file and name the copy after the target language, for example
en.jsontode.json. - Translate every text value. Keep each key exactly as it is, and copy placeholders like
{name},{{count}}or%sinto the translation unchanged. - Check that the file is still valid JSON. Your code editor flags a broken file, and so does any online JSON validator.
- Load it in the app and click through the screens in the new language.
Doing step 2 by hand is fine for a few dozen strings. For a few thousand, or for ten languages, it’s where a translation tool earns its keep.
Mistakes That Break a Translated JSON File
- Translating a key. Change
"title"to"titel"and the app no longer finds the text, so it shows the raw key or falls back to the original language. - Translating a placeholder.
{name}becomes{nom}and your French users see a literal{nom}instead of their own name. - Unescaped quotes. A straight quote
"inside a translation ends the value early and breaks the whole file. Inside a value it has to be written as\". - A missing or extra comma. JSON allows no comma after the last item in a list or object, and one stray comma stops the file from loading at all.
- Plural messages. Some apps use the ICU format, like
{count, plural, one {# item} other {# items}}. The words inside need translating, the structure around them doesn’t, and many languages need more plural forms than English. - The wrong encoding. Save the file as UTF-8, or accented letters and other alphabets turn into question marks.
Before You Upload the File
- Look for text in plain lists. Text sitting directly in a list, such as
"sizes": ["Small", "Medium", "Large"], has no key of its own and isn’t translated. If your lists hold text people see, translate those few items by hand afterwards, or, if you own the code, give each item a key, for example[{"label": "Small"}]. - Move URLs and IDs out of text values if you can. Every text value is sent for translation and counted, including a link or a product code stored as text.
- Keep HTML inside values simple. A
<b>or a link inside a value is translated along with the words around it, and the tags can come back moved or changed. Search the translated file for<and compare those lines with the original.
How to Translate a JSON File with Taia
Taia is an online translation platform that reads JSON files directly, so you don’t paste strings into a chat window and copy them back one by one.
- Upload the .json file at translate.taia.io and pick your target languages. One project can take several languages at once.
- Choose AI or a professional translator. AI gives you a first draft of every string in minutes, which you or someone on your team can then review. If you’d rather have a person translate it, a professional linguist can translate and review it instead.
- Download the translated JSON file, then load it in your app and test it as usual.
What it takes care of for you:
- Keys and structure stay as they are. Only the text values are translated. Keys, nesting, the order of entries, numbers,
true,falseandnullcome back exactly as you sent them. - Placeholders are protected. The AI translation keeps
{name},{{name}},${name},%s,%dand%1$sunchanged, though a quick search for them before release is still worth it. In the Translation Editor (Pro) they show as normal text, so take care not to change them when you edit a string by hand. ICU plural messages are translated as text, so have someone check those. - The file stays valid. Quotes and line breaks in a translation are escaped for you when the file is written.
- Only text is counted. Keys and numbers never reach the word count, so only the words people will read use credits or go into a quote.
- Your terminology carries over. On Pro, a glossary and a translation memory keep button labels and product names the same in every release. More on that in the AI Translator.
Two honest limits: text in a plain list without a key comes back untranslated, as described under Before You Upload. And forward slashes come back escaped, so https:// reads https:\/\/ in the file. Every JSON parser reads both as the same text, but your diff will show the change.
How Much Does It Cost?
JSON files are included on every plan, including Free, with 5,000 credits a month (5,000 words with Standard AI). Basic is €9/month for 20,000 credits (20,000 words with Standard AI). Pro is €39/month for 100,000 credits (100,000 words with Standard AI) and adds all 204 languages, translation memory and glossary. If you’d rather have a person do it, professional translation is billed per word from €0.06, with no subscription. Taia handles 65+ formats, including XML and, on Pro, PO if your strings also live there.
When Your JSON Files Change Every Release
You can upload the updated file each time, and on Pro the translation memory steers the AI toward the wording you approved last time, so less changes between releases and there’s less to review. If you’d rather not pass files around at all, the next step is continuous localization, where new and changed strings flow to translation on their own and come back translated. That’s what we’re building Strings for.
With Strings, a command line tool will push new and changed strings from your repository or CI pipeline to Taia and pull approved translations back, so only approved translations reach your build. JSON is one of the string file formats we’re working on, alongside PO, iOS and Android files. Strings isn’t public yet: join the Strings waitlist for early access by invitation.
Frequently Asked Questions
Are the keys in a JSON file translated?
No. Only the text values are translated. In "title": "Your cart", the key title stays exactly as it is and only Your cart changes, so your code still finds every string.
What happens to placeholders in a JSON file?
The AI translation protects them, so {name}, {{name}}, ${name}, %s, %d and %1$s should come back unchanged, though a quick search for them before release is still worth it. ICU plural messages like {count, plural, ...} contain words that need translating, so have someone check those before you ship.
Is text inside an array translated?
Only when it has a key. Text sitting directly in a list, such as ["Small", "Medium", "Large"], comes back untranslated. A list of objects, such as [{"label": "Small"}], is translated like the rest of the file.
Can I translate a JSON file with Google Translate or a chat assistant?
For a short file, yes, by pasting the text in and copying the result back. The risk is that a key, a quote or a placeholder changes along the way and the file stops loading. A tool that reads JSON translates only the values, and with Taia a glossary and translation memory keep your terms the same in every release.
Can I translate a JSON file for free?
Yes. JSON files are included on Taia’s Free plan, with 5,000 credits a month (5,000 words with Standard AI). You get a translated JSON file back, with your keys and structure intact.
How much does it cost to translate a JSON file?
With Taia, AI translation of JSON files is included on every plan, from Free (5,000 credits a month, or 5,000 words with Standard AI) to Pro at €39/month for 100,000 credits (100,000 words with Standard AI). Only text values are counted, never keys or numbers. Professional translation is billed per word from €0.06, with no subscription.