JSON Localization Guide: Strings, Variables and QA

Last reviewed: 4 October 2026

Short answer

Translate the user-facing values in a JSON resource file while preserving the application's key structure and agreed message syntax. Provide context, protect variables, validate JSON, and test messages in the actual product. JSON supplies a data format; it does not define how every localization library interprets nesting, plurals or markup. Document the framework and resource conventions before exchanging files.

Key takeaways

Keep resource keys stable unless engineering approves a migration.
Translate complete messages rather than assembled fragments.
Treat interpolation tokens as protected data contracts.
Separate JSON validity from framework and interface correctness.
Keep context notes outside runtime resources unless the loader supports them.
Include failure states, plurals and long dynamic values in QA.

What belongs in a translatable JSON resource?

Include text the customer sees: labels, instructions, errors, notifications and relevant accessibility text. Keep operational data outside the translation scope unless its meaning is explicitly localized. A file extension alone cannot tell a translator which values may change.

Agree a resource contract. Identify the library, namespaces, key separators, interpolation syntax, permitted markup and expected return types. A JSON file used for configuration may contain booleans, numbers and identifiers that should remain untouched. The team should distinguish it from a message catalog before sending it for translation.

RFC 8259 defines JSON values and recommends unique object member names.[1] A successful parse does not detect every project-level mistake. For example, a loader may accept an object where the screen expects a string, or a duplicate name may already have discarded information during parsing.

How should keys and nesting be designed?

Use names that describe the message's product purpose and keep the structure predictable. A stable key such as quote.received gives engineering a durable reference while the displayed text evolves. Decide whether dots represent paths or literal characters in your chosen loader.

Avoid a universal key named continue if different screens need different actions. A payment confirmation, account setup and document upload can require different Vietnamese wording. Share a message only when its meaning and constraints are genuinely shared; otherwise create contextual keys and explain the distinction.

The following original pair uses nested objects and i18next-style named tokens. It is a resource example, not a complete application integration. The English source is:

{
  "quote": {
    "title": "Request a quotation",
    "received": "We received request {{requestId}}.",
    "fileLimit": "Attach files totaling less than {{limit}}.",
    "nextStep": "Request received.\nOur team will review it."
  },
  "account": {
    "welcome": "Welcome, {{name}}.",
    "saveChanges": "Save changes"
  }
}

The Vietnamese target preserves the same paths and tokens:

{
  "quote": {
    "title": "Gửi yêu cầu báo giá",
    "received": "Đã nhận yêu cầu {{requestId}}.",
    "fileLimit": "Đính kèm tệp có tổng dung lượng dưới {{limit}}.",
    "nextStep": "Đã nhận yêu cầu.\nĐội ngũ sẽ xem xét nội dung."
  },
  "account": {
    "welcome": "Chào {{name}}.",
    "saveChanges": "Lưu thay đổi"
  }
}

The limit is supplied by the application, not invented by the translator. Both languages should describe the same boundary. If the system permits a total up to a value including equality, the source message itself needs a different statement; translation should not silently repair an undocumented business rule.

How should variables be protected?

Preserve each variable name and delimiter exactly, while allowing the sentence to place it naturally. i18next documents named interpolation tokens and escapes values by default.[2] Other libraries can use different syntax and rendering rules, so the brief must specify the actual environment.

Record the data behind each variable. Is name a person's display name, an organization or a file? Is limit already formatted with a unit? Does requestId contain characters that need special handling in the destination? Those answers influence translation and testing.

Use full sentences with movable tokens instead of concatenating “Welcome” and the user's name in separate fragments. Keep punctuation in the message where practical. Do not translate the token into {{ten}}, add spaces inside a protected identifier or hard-code a sample customer name.

Resource decision	Translator may change	Must be reviewed separately
User-facing message	Wording and natural word order	Meaning and action
Key or object path	Normally nothing	Engineering migration
Named variable	Position in the sentence	Identifier and delimiter
Numeric configuration	Normally nothing	Product rule and type
Escaped line break	Surrounding text	Whether the renderer uses a new line
Permitted markup	Text within approved structure	Rendering and security policy

How do escaping and line breaks affect translation?

Preserve valid JSON syntax when text contains quotation marks, backslashes or control characters. Use the project's normal serializer and validator rather than manual search-and-replace. RFC 8259 specifies the string escape grammar and interoperable UTF-8 exchange.[1]

In the example, \n is the encoded line break inside a JSON string. After parsing, the string contains a new-line character. Whether the interface shows a visual new line depends on the rendering context; parsing alone cannot prove the final layout.

Review the complete path from source file to screen. A spreadsheet, translation tool and build step can each alter escaping. Exporting a literal backslash followed by n instead of the intended escape can produce visible characters; converting it to an unescaped physical line break inside the quoted JSON value can invalidate the file.

Do not use comments or trailing commas in files that must conform to ordinary JSON. If the project intentionally uses JSONC or another variant, name it accurately and verify the supported tooling. A file accepted by an editor may still fail the runtime loader.

How should plurals and context be handled?

Let the selected localization system determine plural resource conventions. JSON itself has no plural engine. i18next documents count-based selection and version-dependent plural suffixes.[3] Record the library version and test the relevant counts instead of assuming two copied forms fit every language.

An English resource may need different messages for one item and multiple items. A Vietnamese sentence might use the same visible noun across those counts, but the application must still request a valid resource for its configured rule. Test zero, one, several and any special product state that changes the message.

Provide context for words with multiple senses. “Open” can be an action or a status. “Charge” can refer to billing or another domain. Screenshots, adjacent text, character constraints and action descriptions help avoid a grammatically polished message that performs the wrong job.

Nested resources also require loader-specific checks. i18next documents options for returning objects and arrays.[4] Do not assume that reading a parent key automatically returns the final string. Verify whether the application expects a leaf message, a structured value or a collection.

What about HTML and rich text inside JSON?

Treat markup as a separate rendering contract. Prefer structured rich-text handling supported by the application over arbitrary HTML inserted into a translation. Identify permitted tags or component tokens and protect them during translation.

A string that parses correctly can still be unsafe if inserted into an inappropriate HTML context. Do not disable interpolation escaping merely to make formatting appear. Review the framework's escaping, component behavior and any sanitization requirements with engineering. This article does not claim that one escaping setting secures an entire application.

Preview rich messages with realistic values, including quotation marks and characters with special meaning to the renderer. Ensure the translated message does not create new executable behavior or alter an intended link destination. Review accessibility text separately when visible formatting does not represent the spoken message well.

Which common mistakes deserve explicit checks?

Check contract-breaking changes before stylistic polishing. A useful defect includes the resource path, source and target, expected behavior and a reproduction case. The following original matrix helps separate syntax, data and interface problems.

Risk	Reproduction case	Acceptance evidence
Missing key	Request a newly added leaf message	Approved fallback or correct localized value
Renamed token	Render a message with each required variable	No unresolved token and correct data
Duplicate name	Run a duplicate-aware resource lint	No ambiguous object members
Wrong value type	Load a key expected to return text	String matches the resource contract
Broken escaping	Use quotes, backslashes and line breaks	File parses and display matches intent
Incomplete plural mapping	Render zero, one and several	Correct branch in configured library
Wrong context	Open each screen that reuses a label	Meaning matches the action or state
Layout failure	Render long names and Vietnamese text	Readable, operable interface

Treat fallback behavior as a decision, not automatic success. An English fallback can keep a screen usable during development, but may be unacceptable in the approved Vietnamese release. Decide which missing messages block launch and how the team will monitor later additions.

What should the handoff contain?

Deliver validated resources with the context inventory, terminology decisions and unresolved questions. Include the source revision, target language, protected-token list and agreed checks. This makes it possible to compare later exports without guessing which source the translation used.

LocalizeZone recommends sending representative JSON files, screenshots and framework details when requesting software localization. Describe whether the scope includes translation only, linguistic review or testing in a running build. Send the materials through the quotation page so the proposed work reflects the implementation needs.

Before release, perform three layers of review: parse and lint the resource; exercise the framework's lookup and interpolation; inspect the resulting interface. A local file check is useful evidence for the first layer, not a substitute for the other two. Keep release notes explicit about which layers were actually completed.

FAQ

Should translators translate JSON keys?

Usually not. Keys are application references. Translate approved values and change keys only through an engineering-led migration that updates the callers and validation rules.

Can all values in a JSON file be translated?

No. Configuration values, identifiers and data types may be operational. Identify the translatable resource scope before work begins and preserve everything outside it.

Does JSON.parse detect duplicate keys?

It is not a duplicate-aware lint. Use a suitable source-level check when unique names are required, because a parser can accept a file while losing earlier values.[1]

Is {{name}} a universal JSON feature?

No. It is an interpolation convention used by systems such as i18next.[2] JSON stores the string; the chosen runtime interprets its tokens.

Can valid JSON still produce a broken interface?

Yes. Lookup rules, types, tokens, rendering and layout can still fail. Validate the file and test the actual product behavior separately.

What helps estimate the project accurately?

Provide resource files, source revision, screenshots, target languages, framework conventions and release timing. State whether engineers will integrate the files or whether integration review is part of the requested scope.

Sources and methodology

RFC 8259 and official i18next documentation were checked on 4 October 2026. The bilingual resource pair and QA matrix are original examples. Parsing, key-path comparison and protected-token checks are reproducible locally; this guide does not claim an i18next integration test, browser rendering test or full application security assessment.

References

[1] IETF / RFC Editor. RFC 8259: The JavaScript Object Notation Data Interchange Format.

[2] i18next documentation. Interpolation.

[3] i18next documentation. Plurals.

[4] i18next documentation. Objects and arrays.

JSON Localization Guide: Strings, Variables and Common Mistakes