Structured JSON

Learn about localizing Structured JSON (.json) files with Transifex

Nina Eleftheriadou avatar
Written by Nina Eleftheriadou
Updated over a week ago

File Extension(s)

.json

i18n type(s)

STRUCTURED_JSON

Structured JSON uses a JSON-based format for localization. There are five types of entries: string, context, developer_comment, character_limit, and plurals.


Sample data

{
"singular_key":{
"string":"This is a regular string."
},
"total_files":{
"string":"{ file_count, plural, one {You have {file_count} file.} other {You have {file_count}files.} }",
"context":"Additional context:....."
},
"special_chars":{
"string":"{ cnt, plural, one {This is Sam's book.} other {These are Sam's books.} }",
"developer_comment":"This is a pluralized string with special character"
},
"gold_coins":{
"string":"{ cnt, plural, one {You have one gold coin.} other {You have {cnt} gold coins.} \n}",
"character_limit":150
},
"key_1":{
"key_nested_1a":{
"string":"localize"
},
"key_nested_1b":{
"key_nested_1ba":{
"string":"translation tools"
},
"key_nested_1bb":{
"string":"{ minute_count, plural, one {minute} other {{minute_count} minutes} }"
}
}
},
"parent_key":{
"child_key":{
"string":"This is a key from a child",
"context":"Noun",
"developer_comment":"This is a comment.",
"character_limit":150
}
}
}


Description of fields in the structure

  • string: Translatable string (Required).

  • context: Small segment of text used to differentiate from entries with the same string value (Optional).

Structured_JSON_Context_Image.JPG#asset:6293
  • developer_comment: Small description to give context to translators about how the string
    should be translated (Optional)

Structured_JSON_Developer_Notes_Image_small.JPG#asset:6295
  • character_limit: Maximum number of characters the translation can have (Optional)

Structured_JSON_Character_Limit.JPG#asset:6296

Plurals support

Transifex supports pluralized entries in JSON based on ICU's message format specifications (plural subset). For more details about how Transifex handles pluralized strings, please take a look at our documentation guide.

Example:

"files" : "{count, plural, one {You have {count} file.} other {You have {count} files.}}"

For pluralized strings that follow a different structure, for example:

"string" : "{number, plural, =1 {1 New}, =2 {# New}}"

The Structured JSON parser will handle them as simple entries in the editor as follows:

Structured_JSON_Plurals_Support.JPG#asset:6297

๐Ÿ“ Note: Do you want to find out more about plurals in Transifex? Please check here.


Escape behavior

The way the Structured JSON parser escapes special characters is the same as in the case of the Key-Value JSON parser.


Lists

JSON lists are not supported. So, if your file contains the following content:

{
"singular_key":{
"string":"This is a regular string."
},
"json_list":[
"Item 1",
"Item 2",
"Item 3"
]
}

Then, the parser will parse the file, ignoring the json_list entry (this entry wonโ€™t be available in Transifex Web Editor). Once the translations are done, the generated file will look like this:

{
"singular_key":{
"string":"This is a regular string."
},
"json_list":[
"Item 1",
"Item 2",
"Item 3"
]
}

i.e., the json_list entry will be included in the exported translation file in the source language.


Download modes

  • Download file to translate: Any untranslated entries will be returned empty so that translators know which untranslated ones they need to work on.

  • Download for use: Any untranslated entries will be returned in the source language.

  • Download only reviewed translations: Any untranslated string or unreviewed translation will be returned in the source language.

  • Download for translation as XLIFF: The file will be generated in the .xliff format and include both translated and untranslated strings. The latter ones will be returned without containing target elements.

  • Download untranslated strings as XLIFF: The translation file will be generated in the .xliff format and include only the untranslated strings.

  • For more information on download modes via the API or Client, consult the following table:

* The results are compatible with parser version 1.

๐Ÿ“ Note: Proofreading must be enabled for this logic to take effect. To learn how to enable proofreading, click here.


Default placeholders

These are the default placeholders that you could have in your file, and they will be recognized :

match: ['%1$s', '%(key1)s', '%s', '%d', '%.2f', '%-5d', '%+2d']


๐Ÿ’กTip

Looking for more help? Get support from our Transifex Community Forum!

Find answers or post to get help from Transifex Support and our Community.

Did this answer your question?