Structured JSON files are used for managing localization strings with additional metadata properties in a hierarchical format. Lokalise supports structured JSON files, allowing for efficient management of translations along with context, character limits, tags, and notes. This format is ideal for complex localization needs where additional information is required for each translation key.
Technical information
Overview
Format name:
Structured JSON
File extensions:
.json
Common use cases:
Managing and organizing localization strings in web and mobile applications with additional metadata such as context, notes, tags, and character limits.
Technical details:
Structure: Structured JSON files contain entries with multiple properties for each translation key. These properties include the actual translation, notes, context, character limit, and tags.
Encoding: UTF-8
File structure
Here's an example of a typical structured JSON file used for localization:
{
"mm_homepage": {
"translation": "Homepage",
"notes": "Title for main menu",
"tags": [ "main", "important" ]
},
"mm_about": {
"translation": "About us",
"notes": "Title for main menu",
"limit": 20
},
"somekey": {
"translation": "First level key"
},
"somekey::sub": {
"translation": "Second level key"
}
}
In this example, each key contains various properties such as translation, notes, tags, and limit, providing additional information and constraints for the translation.
Supported properties
Structured JSON file entries can contain the following properties:
translation– the actual translation (required)notes– description of the key, providing translators or AI with additional context. (optional)context– used to differentiate keys that share the same name. Two keys can have identical names as long as their context values are different (optional)Important: the
contextfield cannot be updated via file upload. Once a key's context is set, it’s fixed.
limit– character limit for the key (optional)tags– additional tags (optional)
TypeScript Integration
If you are using TypeScript and want to add an autocompletion feature for your key names, you can add the following line of code to your app:
keyof typeof import ('./path/to/some/json/file.json')
Using with Lokalise
Lokalise supports structured JSON files, making it easy to manage and translate your localization strings within the platform.
Supported project types
Please note that JSON files can be uploaded only to Web and mobile projects.
Important distinction between context and notes
context: A technical identifier that helps distinguish otherwise identical keys. It defines unique key identity and cannot be changed through file uploads.notes(or description): A human-readable explanation intended for translators or AI translation tools. Unlikecontext, notes/descriptions can be updated when a new file with changed descriptions is uploaded.