Q: How does Localazy handle nested JSON keys?

Localazy fully supports nested JSON structures, keeping your hierarchy intact throughout the translation process. Each nested key (for example, <code>home.title</code> or <code>buttons.save</code>) is treated as an individual translation entry, making it easy to manage large and organized files. When you upload your JSON files, Localazy automatically detects and preserves the nesting levels, ensuring your exported translations match the original structure exactly. You can also filter or search by key paths (like <code>home.*</code>) to quickly find related strings, and the <a href="https://localazy.com/features/glossary">glossary</a> and <a href="https://localazy.com/features/context-screenshots-ocr">context notes</a> help translators understand where each string is used. This approach allows developers to keep a clean, structured JSON setup while giving translators a flat, easy-to-navigate view in the Localazy interface.

Question 1

How to translate JSON files?

Accepted Answer

You can translate JSON (JavaScript Object Notation) files with the assistance of machine translation engines (such as Google Translator) and copy-paste the results into your text editor. But this translation option is time-consuming and inefficient.

Considering that JSON is one of the most lightweight data interchange formats, working with it is pretty handy. And the best way to translate JSON files is to use an online translation service, such as Localazy. Localazy serves as TMS and localization suite to help you translate your JSON files effectively. With its help, you can translate multilingual JSON files, JSON5 files, or HJSON files and integrate a Translation Management System (TMS) into your workflow.

To translate JSON files using the Localazy interface, sign up for free and create a new translation project. Once you upload your JSON file, you can add the target language, start translating, and then download the translated files with ease. You can even pre-translate the whole file in JSON format by applying machine translations in bulk. This and many other features make Localazy the ideal tool to produce professional translations.

Localazy is a state-of-the-art translation management platform and localization suite to help you translate your JSON files effectively. Learn more in the Getting Started Guide.

Question 2

How to open and edit JSON files?

Accepted Answer

You can use any text/code editor such as Notepad, Sublime Text, and others to open and edit JSON files. Alternatively, use an online editor to edit your JSON files.

However, for JSON files containing strings of texts or translations, you should use Localazy, suitable for managing multiple file formats.

To open and edit JSON files using the Localazy interface, sign up for free and create a new translation project. Once you upload your JSON file, click on the File management tab to view, open and access your file content.

Localazy is a state-of-the-art translation management platform and localization suite to help you translate your JSON files effectively. Learn more in the Getting Started Guide.

Resources #️⃣

CLI: JSON File Format CLI Quick Start - JSON

Question 3

How to convert JSON files?

Accepted Answer

You can use the Format Conversions feature of Localazy to convert JSON files to over 20 other localizable file formats, including Microsoft Excel, PO and XLIFF.

Begin by signing up for free and creating a new translation project. Upload your JSON files and set up the Localazy CLI with the correct configuration. You can also convert JSON files by navigating to File management section in Localazy, from there, locate your JSON file you wish to convert, click the download icon and select the desired format.

Question 4

How to get rid of quotation marks after conversion from JSON to Android XML?

Accepted Answer

Suppose you have a project where the source file is a JSON file with a row in the format:

"about.moreButton": "Learn more on our website",

When using the Localazy CLI to import to Android with Format Conversions (or when you just try to export the JSON file to Android XML inside the Localazy web platform), you might notice that the format is:

<string name="about_moreButton">"Learn more on our website"</string>

Now, you might think you should delete those start and end quotation marks in the body of the XML row to achieve this result:

<string name="about_moreButton">Learn more on our website</string>

However, you can keep the quotation marks in the Android XML file because it’s a supported construct used to correctly encode white characters that would otherwise be lost in all cases. Quotation marks ensure that the exact form of your strings is preserved after conversion.

In actual use, the text will render correctly on the device.

More information can be found on the Android Developers website: String Resources

Question 5

Why are some keys in a JSON object missing from the downloaded files?

Accepted Answer

You might encounter a situation, when not all keys that are a part of the same structure get downloaded from your Localazy project. Most likely, the issue here is that you have the key both as a single text and also as a structure.

This often happens when you first create a key and later decide to actually change it to an object with multiple subkeys.

So at first, you create a key, e.g.: user.welcome with text “This is a welcome text.”

But then, you decide you want to use a structure such as:

user.welcome.text => “This is a welcome text.”
user.welcome.title => “Welcome title”

Supposed it is a nested JSON, then you can’t have both:

{
"user.welcome": "This is a welcome text.",
}

and at the same time use:

{
"user.welcome": {
"text": "This is a welcome text",
"title": "Welcome title"
}
}

Because the same key can not be an object and a text at the same time.

In the future, you can simply prevent this, by using deprecating during upload so old keys are automatically marked as deprecated when they are no longer part of the uploaded file. In your CLI configuration, set deprecate to value project, and all keys missing in the upload batch across whole project will be deprecated.

Question 6

Why use Localazy for managing JSON translations?

Accepted Answer

Working with JSON translation files by hand can quickly turn into a complex and error-prone task, especially when your app supports multiple languages or involves several contributors. Localazy helps you simplify and automate this process through:

Seamless CLI integration that automatically syncs JSON files with your codebase.
AI and machine translation support to instantly translate new or updated strings.
A clean, user-friendly editor that lets translators make changes safely without developer input.
Centralized translation management, ensuring one reliable source for all your language files.
Collaborative workflows that keep developers, translators, and reviewers perfectly aligned. Once your project is connected, Localazy keeps your JSON files up to date in every language — saving time, reducing errors, and allowing your team to focus on development instead of manual translation maintenance.

Question 7

What’s the best structure for i18n JSON files?

Accepted Answer

A good JSON file structure should be consistent, human-readable, and scalable as your app grows. Most i18n setups use key-value pairs, where each key represents a translatable string, and values are the translations.

{
  "home": {
    "title": "Welcome",
    "description": "Your productivity hub"
  },
  "buttons": {
    "save": "Save",
    "cancel": "Cancel"
  }
}

This nested structure keeps related strings grouped logically (e.g., by screen or feature) and makes maintenance easier. Avoid repeating the same text across files — instead, reuse common keys where possible. Localazy supports any standard i18n JSON format, helping you upload, translate, and export your files effortlessly. You can also define custom file structures and naming patterns to match your project setup.

Question 8

How does Localazy handle nested JSON keys?

Accepted Answer

Localazy fully supports nested JSON structures, keeping your hierarchy intact throughout the translation process. Each nested key (for example, home.title or buttons.save) is treated as an individual translation entry, making it easy to manage large and organized files.

When you upload your JSON files, Localazy automatically detects and preserves the nesting levels, ensuring your exported translations match the original structure exactly.

You can also filter or search by key paths (like home.*) to quickly find related strings, and the glossary and context notes help translators understand where each string is used.

This approach allows developers to keep a clean, structured JSON setup while giving translators a flat, easy-to-navigate view in the Localazy interface.

Question 9

How to manage plurals and variables in JSON translations?

Accepted Answer

Localazy supports pluralization and dynamic variables in JSON translations, helping you handle language-specific rules with ease.

Localazy recognizes JSON objects or arrays that follow standard plural types (e.g. one, other, few, many, zero, etc.).

{
  "items": {
    "one": "You have 1 item.",
    "other": "You have %d items."
  }
}

You can also use plural suffixes in keys (e.g. itemOne / itemOther, item_one / item_other, or bracketed forms like item[one] / item[other]) — Localazy can detect and preserve your input format.
If you prefer ICU-style plurals, Localazy supports that too (via plural_icu feature). For example:

{
  "items": "{count, plural, one {1 item} other {# items}}"
}

Localazy will convert that into its internal plural handling for each language.

You can include placeholders (like {count}, {name}, %d, etc.) inside your strings. Translators see them and can place them as needed in the translation. Localazy ensures that those placeholders stay intact.

Handling pluralization properly matters for several reasons:

It allows you to handle complex grammar rules (singular, plural, dual, etc.) automatically.
Translators see only the relevant plural forms for their language, reducing confusion and mistakes.
You don’t need to manually code plural logic for every language — Localazy (with your app) will handle the mapping.

Question 10

How to deal with placeholders and interpolation in JSON strings?

Accepted Answer

Placeholders are essential in dynamic texts — for example, messages like "Welcome, {username}!" or "You have {count} new notifications." In JSON translations, these variables must stay intact across all languages to prevent runtime errors or formatting issues.

Localazy automatically recognizes common placeholder patterns such as {variable}, %s, or ${value}. During translation, it protects them so translators can’t accidentally modify or delete them. Each placeholder appears clearly highlighted in the editor, making it easy to understand where and how it will appear in the final text.

To keep translations accurate, you can also:

This approach keeps your JSON translations both developer-friendly and safe for dynamic, variable-rich content across multiple languages.

Question 11

How to automate JSON translation updates in CI/CD pipelines?

Accepted Answer

Automating JSON translation updates ensures that your app’s localization stays in sync with development changes, reducing manual work and minimizing errors. Localazy can be integrated directly into your CI/CD workflow, enabling automatic upload and download of translation files during build and deployment processes.

Key steps to automate JSON translations with Localazy:

Upload new or updated JSON strings automatically When using the Localazy CLI or API, a merge into the main branch can trigger an automatic upload to Localazy without manual intervention.
Automatic machine translations Once uploaded, Localazy can pre-translate new strings, so translators only need to review or refine them, speeding up the localization process.
Pull translations before build/deployment Your CI/CD scripts can fetch the latest translations from Localazy, ensuring that your app always includes up-to-date JSON files for all supported languages.
Integration with version control Combined with Git or other VCS (Version Control System), you can track translation updates alongside your code, avoiding conflicts and maintaining a single source of truth.
Optional notifications and checks Pipelines can trigger alerts if translations are missing, placeholders are inconsistent, or plural forms are incomplete, allowing automated QA before deployment.

By embedding Localazy into your CI/CD workflow, your development team can focus on building features while translation updates run seamlessly in the background, keeping your JSON files synchronized across all environments and languages.

Question 12

What’s the difference between flat and nested JSON localization formats?

Accepted Answer

JSON localization files can be organized in flat or nested formats, and choosing the right structure affects readability, maintainability, and integration with your app.

Flat JSON #️⃣

All translation keys are at the top level, usually with dot-separated paths representing hierarchy:

{
  "home.title": "Welcome",
  "home.description": "Your productivity hub",
  "buttons.save": "Save",
  "buttons.cancel": "Cancel"
}

Advantages: easy to search and reference keys programmatically; simpler for some i18n frameworks.
Drawbacks: less visually organized, harder to group related strings for translators.

Nested JSON #️⃣

Keys are organized hierarchically using objects, reflecting the app’s structure:

{
  "home": {
    "title": "Welcome",
    "description": "Your productivity hub"
  },
  "buttons": {
    "save": "Save",
    "cancel": "Cancel"
  }
}

Advantages: visually clear, groups related content logically, easier for translators to understand context.
Drawbacks: some frameworks or automation scripts may require flattening before use.

Localazy supports both flat and nested JSON formats, allowing you to upload, translate, and export files without losing structure. You can also choose the preferred format for your project, ensuring consistency across environments and repositories.

Question 13

Can I keep my JSON formatting and key order when syncing?

Accepted Answer

Localazy preserves the overall JSON structure and syntax style (such as indentation, quoting, and multi-line formatting) when exporting translations, so the exported JSON files remain valid and consistent with your project’s formatting style.

However, the exact key order from your source files isn’t stored. Localazy extracts translation keys and reconstructs JSON files upon download, which means keys may appear in a different order (usually alphabetically or by the order of creation in the database). This doesn’t affect how your app reads translations, since key order in JSON has no functional meaning.

Question 14

How to avoid losing context for translators when using JSON keys?

Accepted Answer

Depending on the type of content, JSON files may use short or technical keys (like "msg1" or "btn2"). While these are meaningful to developers, translators don’t always see where or how the text is used. To keep translations clear and consistent, Localazy lets you add helpful context directly in the platform.

You can:

Add descriptions or screenshots so translators understand where each string appears in the app or website.
Group related strings by tags (for example, all texts from one page or feature) to give translators a better sense of context.
Use the Glossary to define product-specific terms, brand names, or preferred tone.

These features help translators better understand the intent and use of texts, even when key names alone don’t fully convey meaning, resulting in more accurate and natural translations across all languages.

Question 15

How to sync JSON translations across multiple environments or repositories?

Accepted Answer

When your app spans several environments (for example, web, mobile, or desktop) or separate repositories, keeping JSON translations aligned can be challenging. Without proper syncing, it’s easy for updates to fall out of sync or for translators to repeat work unnecessarily.

Localazy helps maintain consistency across projects in a couple ways:

Connected Projects allow you to share translations (via translation memory) across multiple projects. By setting up automation to apply translation memory, identical strings can reuse existing translations from related projects instead of being translated again.
Duplicity Linking lets you explicitly link identical keys across projects. Changing a string in one project can propagate updates to all linked counterparts, keeping your translation content uniform.

Altogether, these tools reduce repetitive translation work and simplify the management of shared content across different environments and repositories.

Question 16

What are common pitfalls when localizing JSON-based apps?

Accepted Answer

Localizing JSON-based apps can be straightforward, but there are several pitfalls to watch out for:

Unclear or cryptic keys: keys like "msg1" or "btn2" may give very little context to translators, leading to inaccurate translations. Always provide descriptions or context notes.
Inconsistent placeholders: failing to preserve {variables} or %s placeholders can break runtime messages. Use Localazy’s placeholder highlighting and QA checks to avoid this.
Ignoring plural forms: many languages have complex plural rules. Translating only the English singular or plural can result in incorrect messages in other locales.
Broken JSON syntax: missing commas, braces, or quotes can make JSON files unreadable by the app, which results in an error message stating that the file cannot be uploaded.
Divergent key structures across environments: differences in key hierarchy or naming between repositories can lead to confusion or duplicate translations. Localazy’s connected projects and duplicity linking help reuse translations across projects, but they don’t replace disciplined key naming and repository practices.
Overwriting translations: Manually editing JSON files without tracking changes can overwrite previous translations. Using Localazy ensures a single source of truth for all languages.

Question 17

How to validate JSON translations before deployment?

Accepted Answer

Validating JSON translations ensures that your app functions correctly and that all localized content appears as intended. Common issues include syntax errors, missing keys, incorrect placeholders, or inconsistent plural forms, all of which can break your app if left unchecked.

Localazy helps you catch these issues before deployment:

JSON upload validation: Localazy only accepts valid JSON files. If the syntax is broken (missing braces, commas, or quotes), the file cannot be uploaded, and an error message about an unsuccessful upload will be shown.
Placeholder validation: placeholders (like {username} or %d) are highlighted to ensure they are preserved correctly across all languages.
Plural and ICU checks: for pluralized strings, Localazy verifies that all required forms for each target language are present.
Duplicity linking: you can link identical keys across projects, which allows updates in one project to propagate to linked keys in other projects, helping maintain consistent translations across environments.

By using these features, you can catch issues early, maintain high translation quality, and confidently deploy your JSON-localized app without breaking functionality or user experience.

File Formats

💡 Enough theory, try Localazy now! 🚀