Add-in for JavaScript Object Notation (JSON) file format types
JSON (JavaScript Object Notation) is a lightweight data-interchange format. The add-in for JSON file formats is available starting with service pack 8 (SP8) of SDL Passolo.
Since the JSON add-in was introduced, along with SP8, it initially only supported RESJSON and ARB file formats. Support for parsing JSON files was made available starting with service pack 9 (SP9) of Passolo
It is easy for humans to read and write, while it is also easy for machines to parse and generate.
It is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999.
JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others.
{
"menu":
{
"id": "fileId",
"value": "File",
"popup":
{
"menuItem":
[
{ "value": "New", "onclick": "CreateNewFile()"},
{ "value": "Open", "onclick": "OpenFile()"},
{ "value": "Close", "onclick": "CloseFile()"}
]
}
}
}
Among the Passolo JSON parser supported types, there are the Windows JavaScript Resources (RESJSON) and Application Resource Bundle (ARB) formats
Parser for JavaScript Object Notation (JSON) files
JSON parser is the main parser of the JSON addin. It will parse a JSON file provided it has a correct format and will parse all string entries. For example, take following JSON structure, which can be used to describe this add-in:
{
"Addin":
{
"product": "Passolo",
"name": "JSON Add-in",
"supportedParsers":
{
"parsers":
[
{
"name": "json",
"description": "JavaScript Object Notation"
},
{
"name": "arb",
"description": "Application Resource Bundle"
},
{
"name": "resjson",
"description": "Windows JavaScript Resources"
}
]
}
}
}
Resources view for the above file looks like the following:
Handling of JSON string resources
C-Style comments
JSON standard format does not support C-Style comments. Addin C-Style comments to a JSON file will break their format. Passolo, however, knows how to handle these comments as long as they are written correctly.
Now, let's look at following user story: an English-speaking developer want to translate this JSON to German. They pass this JSON file to an English-to-German translator, but they also leave developer notes for the translator to know what not to translate.
For this, they alter the JSON file, adding a comment above their respective parsed strings:
{
"Addin":
{
"product": "Passolo",
"name": "JSON Add-in",
"supportedParsers":
{
"parsers":
[
{
"name": "json",
// Please only translate this
"description": "JavaScript Object Notation"
},
{
"name": "arb",
// Please only translate this
"description": "Application Resource Bundle"
},
{
"name": "resjson",
// Please only translate this
"description": "Windows JavaScript Resources"
}
]
}
}
}
The comments that were added in the JSON file now appear in the Passolo stringlist:
And the translator now knows only to translate specific strings, as shown below:
When generating the target file, it will look like the following:
{
"Addin":
{
"product": "Passolo",
"name": "JSON Add-in",
"supportedParsers":
{
"parsers":
[
{
"name": "json",
"description": "JavaScript Objekt Notenschrift"
},
{
"name": "arb",
"description": "Anwendung Ressourcenpaket"
},
{
"name": "resjson",
"description": "Windows-JavaScript-Ressourcen"
}
]
}
}
}
You can see that, upon generating the file, in addition to the string translations, the comments got discarded, since they are not supported by JSON format and the target file needs to be valid.
RESJSON-style comments
Besides C-style comments, you can also have RESJSON-style comments in standard JSON files and set up Passolo to correctly process them.
Our English-speaking developer might want to leave descriptive comments in a JSON file:
{
"addin": "JSON Add-in",
"_addin.comment": "This is the add-in's name",
"json_parser":
{
"name": "json",
"_name.comment": "This is the name of the parser",
"description": "JavaScript Object Notation",
"_description.comment": "This is the description of the parser"
},
"arb_parser":
{
"name": "arb",
"_name.comment": "This is the name of the parser",
"description": "Application Resource Bundle",
"_description.comment": "This is the description of the parser"
},
"resjson_parser":
{
"name": "resjson",
"_name.comment": "This is the name of the parser",
"description": "Windows JavaScript Resources",
"_description.comment": "This is the description of the parser"
}
}
The translator will see the developer's comments in Passolo:
If the Do not write comments to target files option is enabled, the resulted translated file will look like this:
{
"addin": "JSON Add-in",
"json_parser":
{
"name": "json",
"_name.comment": "This is the name of the parser",
"description": "JavaScript Object Notation",
},
"arb_parser":
{
"name: "arb",
"description": "Application Resource Bundle",
},
"resjson_parser":
{
"name: "resjson",
"description": "Windows JavaScript Resources",
}
}
Parser for Windows JavaScript Resources (RESJSON) files
{
"greeting": "Hello",
"_greeting.comment": "A welcome greeting.",
"_greeting.source": "Hello"
}
Resources in RESJSON files
Multiple string entries are read from the RESJSON file, forming the String Table. The String Table contains all the entries to be translated. The source string is read from the key starting with "_" (underscore) and ending with ".source". The translator comments are extracted and displayed in Passolo's string list of the translation window. The translator's comment remains unchanged in the target file.
Translation of plural forms
The string entries of the RESJSON file can contain information on the plural forms supported in the file. Passolo supports this function and offers multiple entries for translation according to the Source\Target Language settings.
Example:
English (en) and German (de) languages have 2 plural forms (one, other), while Japanese (ja) has only one (other). The Welsh (cy) and Arabic (ar) are the only languages to contain all the plural forms (zero, one, two, few, many, other).
An entry in english language (plural forms : one, other) can then have the following form:
{
"greeting": "Hello_value",
"_greeting.comment": "A welcome greeting.",
"_greeting.source": "Hello_source",
"farewell": "Goodbye",
"_farewell.comment": "A goodbye.",
"PLURAL": "{'one': 'element', 'other': 'elements'}"
"_PLURAL.comment": "A comment for the pluralisation forms"
In this case the first two entries are normal entries, while the third entry has two plural forms (one, other with the values "element" and "elements", respectively). All of the plural forms are shown in the string list, absent values appear as empty strings so that all plural forms can be entered for translation to any language. All the plural forms are generated in the stringlist respecting the following rule: [plural_Id].[plural_Form].
Please note that, because missing values or unsupported plural forms appear as empty strings, you should enable the option to display empty strings in translations list. For this, please select from Passolo. In the Options dialog, click on View, then for Display empty strings in translation lists select always. After this, click OK.
In this particular case, PLURAL.zero, PLURAL.one, PLURAL.two, PLURAL.few, PLURAL.many and PLURAL.other will be generated. Also, if a plural id has comments (which is true for our case), that comment will be applied to all the [plural_Id].[plural_Form] strings generated for that plural id, like below:
The Japanese language has only one plural form, which is other. For the Japanese target language, only the other plural form is required to be translated. The other plural forms will be discarded when the target file is generated.
Using the above input, the following output file will be generated:
{
"greeting": "今日は",
"_greeting.comment": "A welcome greeting.",
"_greeting.source": "Hello_source",
"farewell": "ごきげんよう",
"_farewell.comment": "A goodbye.",
"PLURAL": "{'other': '要素'}",
"_PLURAL.comment": "A comment for the pluralisation forms"
}
Parser for Application Resource Bundle (ARB) files
Application Resource Bundle (abbr. ARB) is a localization resource format that is simple (based on JSON), extensible (vocabulary can be added without affecting existing tools and usage), and directly usable (applications can access the resource directly from this format without converting to another form).
In ARB, localizable resources are encoded as a JSON object. Each resource will have a resource entry identified by resource key, and an optional resource attribute entry with resource attribute key.
{
"@@locale": "en_US",
"@@context": "System Administration page",
"HOME_PAGE_TITLE": "Home page!",
"HOME_PAGE_USER_NAME": "Welcome {{user.name}}!",
"HOME_PAGE_DRAWING_COUNT": "{'0': 'You have no Drawings.', 'one': 'You have 1 Drawing.', 'other': 'You have {} Drawings.'}",
"@HOME_PAGE_DRAWING_COUNT": {
"type": "text",
"description": "Number of drawings",
"source_text": "{'0': 'You have no Drawings.', 'one': 'You have 1 Drawing.', 'other': 'You have {} Drawings.'}",
"placeholders": {
"COMMENTSNUM": {
"example": "7",
"description": "number of comments. should be bigger than 1"
}
}
}
}
The ARB file parser supports the following for ARB files:
- Plural and Gender support (identifies plurals and separates them for ease of use during translation. Also generates corresponding plurals in translation list according to the selected language, either one or multiple languages)
-CSS resource
-Resource attributes
-Predefined resource attributes
-Global attributes
-Customized attributes
-Resource Linking
-Single line and multiline comments inside the file
Resources in ARB files
Multiple string entries are read from the ARB file, forming the String Table. The String Table contains all the entries to be translated. The resource id (left of : ) is be visible to the translator as it is typically the case in SDL Passolo, the string to the right is the resource value that is translatable.
On top level in ARB resource structure, there could be a set of "global" attributes that apply to resource bundle as a whole. Those attribute names are prefixed with "@@" to avoid possible conflicts with attribute key of resource with the same name. These special kind of atributes are blocked from translation but preserved into the generated target file.
Resource attributes (ID starting with @ and matching other resource id) data are blocked from translation, and presented to the translator as extra info to help make a quality translation. Other supported attribute types are: type, context, description, placeholders, source_text, etc.
Support for plural forms
As already mentioned the string entries of the ARB file can contain information on the plural forms supported in the file. Passolo supports this function and offers multiple entries for translation according to the Source\Target Language settings.
In the example from above the value for HOME_PAGE_DRAWING_COUNT uses special syntax which is interpreted as a plural string. Certain parts of the string like "one", "other" are not translated.
Per-project settings
Do not write comments to target files
This setting allows not to write comments to target file
Source file settings
Do not write metadata to target files
This setting only applies to ARB and RESJSON parsers. This is because ARB and RESJSON formats naturally support coments.
This setting allow metadata to not be written to target file. This will also be available only for ARB and RESJSON and will create a simple one-level JSON structure, while all metadata and comments are removed