Difference between revisions of "LRM JSON Support"

From Lingoport Wiki
Jump to: navigation, search
(Sample LRM Project Definition File for .json)
(Sample LRM Project Definition File for .json)
 
(37 intermediate revisions by 3 users not shown)
Line 1: Line 1:
LRM supports .json files which makes sense for translation. Not all .json files do.
+
LRM supports those .json files which makes sense for translation. Not all .json files do. The JSON extension as well as file extensions using the json parser type are supported in Lingoport Resource Manager (LRM). Well-formed JSON is required and specified by http://www.ietf.org/rfc/rfc4627.txt. In order to detect and import changes,
   
  +
== Example of JSON files or file extensions using the ''json'' parser type ==
== Sample LRM Project Definition File for .json ==
 
  +
'''Simple JSON object'''
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
 
  +
{
<lrmconf>
 
  +
"the_cat": "The Cat has changed",
<model-version>3.0.18</model-version>
 
  +
"the_dog": "The dog",
<project-name>search</project-name>
 
  +
"the_bird": "The bird"
<project-desc>Search project</project-desc>
 
  +
}
<group-name>Lingoport</group-name>
 
  +
<top-level-dir>/var/lib/jenkins/jobs/Lingoport.search/workspace</top-level-dir>
 
  +
'''Another form of the simple JSON file'''
<detect-errors>
 
  +
{
<missed-trans-error>0</missed-trans-error>
 
  +
"the_cat":
<parameter-mismatch-error>1</parameter-mismatch-error>
 
  +
"The Cat",
<track-back-locale>br</track-back-locale>
 
  +
"the_dog": "The dog",
<target-locales>
 
  +
"the_bird":
<locale>es</locale>
 
  +
"The bird has flown"
<locale>fr</locale>
 
  +
}
<locale>ja</locale>
 
  +
</target-locales>
 
  +
'''JSON objects'''
<default-locale>en</default-locale>
 
  +
{
<resource-extensions>
 
  +
"the_cat": "The Cat",
<resource-extension>
 
  +
"vehicles": {
'''<extension>json</extension>'''
 
  +
"car": "Auto",
'''<file-name-pattern>*_l-c-v</file-name-pattern>'''
 
  +
"bike": "Bike has changed"
'''<use-pattern-on-dflt-locale>1</use-pattern-on-dflt-locale>'''
 
  +
},
'''<file-location-pattern/>'''
 
  +
"colors": {
'''<use-location-pattern-on-dflt-locale>0</use-location-pattern-on-dflt-locale>'''
 
  +
"blue": "Blue",
'''<base-file-encoding>UTF-8</base-file-encoding>'''
 
  +
"red": "Red"
'''<localized-file-encoding>UTF-8</localized-file-encoding>'''
 
  +
}
'''<parameter-regex-pattern><![CDATA[\{\w+\}|%[ds]]]></parameter-regex-pattern>'''
 
  +
}
</resource-extension>
 
  +
</resource-extensions>
 
  +
'''JSON nested objects'''
<dirset>
 
  +
{
<includes>
 
  +
"the_cat": "The Cat",
<include-dir>**/**</include-dir>
 
  +
"dogs": {
</includes>
 
  +
"pitbull": "A pitbull",
<excludes>
 
<exclude-dir-file/>
+
"collie": "A collie",
  +
"small_dogs": {
<exclude-dir-file>**/*_eo.json</exclude-dir-file>
 
  +
"poodle": "A teacup poodle"
<exclude-dir-file>**/*_eo__*.json</exclude-dir-file>
 
  +
}
<exclude-dir-file>**/*_br.json</exclude-dir-file>
 
  +
}
<exclude-dir-file>**/LRMScans/**</exclude-dir-file>
 
  +
}
<exclude-dir-file>**/GlobalyzerScans/**</exclude-dir-file>
 
  +
<exclude-dir-file>**/sonar-project.properties</exclude-dir-file>
 
  +
Although JSON files do not support comments, LRM has created a way to be able to add a comment to a json file in order to work with prep-kits. The '''config_lrm_info.properties''' file, which is a group level file, sets the character that denotes a comment. The default pattern is a line that starts with '_':
</excludes>
 
  +
</dirset>
 
  +
### JSON Comment Pattern ###
</lrmconf>
 
  +
json.comment.starts.with=_
  +
  +
So a comment can be added to a JSON file like:
  +
  +
{
  +
"the_cat": "The Cat hates mice",
  +
"the_dog": "The dog",
  +
"_comment": "This comment key is defined in file 'config_lrm_info.properties' located in L10nStreamlining.",
  +
"the_bird": "The bird"
  +
}
  +
  +
A sample config_lrm_info.properties file can be found in '''<HOME>/lingoport/lrm-server-x.y/deploy/templates/dir_structure/group/config'''.
   
== Example of Supported .json Files ==
 
   
 
=== Simple is Best ===
 
=== Simple is Best ===
A file with <b>one key value per line</b>, with some possible semantics in the key, is the preferred way to have .json resource bundles. There is no structure (no objects) to the file, so changing keys, moving them around, does not affect whatever outstanding translation will be returned at a later date with a different structure.
+
A file with <b>one key value per line</b>, with some possible semantics in the key, is the preferred way to have .json resource files. There is no structure (no objects) to the file, so changing keys, moving them around, does not affect whatever outstanding translation will be returned at a later date with a different structure.
 
<b>resources_en.json</b>
 
<b>resources_en.json</b>
 
{
 
{
Line 66: Line 77:
   
 
<b>Caveat</b>
 
<b>Caveat</b>
JSON structure changes can lead to problems with project on-boarded for file deltas (v. Full Files).
+
JSON structure changes can lead to problems with project on-boarded for file deltas (v. Full Files).
   
  +
== ''json'' parser type ==
== Example of a Non-Supported .json File ==
 
  +
=== valid json syntax ===
  +
Files that use the ''json'' parser are expected to have valid json syntax
   
  +
=== .json uses the ''json'' parser type===
 
  +
When defining a project containing LRM Standard .json resource files, there is no need to define a ''&lt;parser-type&gt;'' as the ''json'' parser will always be used.
   
  +
=== unique file extension needs to define ''json'' parser type ===
  +
If a unique file extension is a valid json file, then the ''&lt;parser-type&gt;'' should be ''json'' in the project definition file.
   
== In what format should JSON Files be for LRM Handling ?==
+
== In what format should JSON Files or files extensions using the ''json'' parser type be for LRM Handling ?==
  +
JSON extension is supported in The Lingoport Manager (LRM) 2.1 release. Well-formed JSON is required and specified by http://www.ietf.org/rfc/rfc4627.txt. In order to detect and import changes, LRM 2.1 requires JSON files to also adhere to the following standards.
 
  +
===Arrays are not allowed in the context of JSON files as resource bundles===
* The json files must follow this naming convention: '''filename_<locale>.json''' or '''filename_<locale>_<country>.json'''. For example, '''resources_en.json''' or resources_en_US.json, '''resources_fr.json''' or resources_fr_FR.json, etc.
 
  +
String references in the code, from an i18n point of view, is unmanageable for JSON arrays. In addition, many L10n vendors do not support JSON arrays.
* '''If you can, avoid duplicate file names'''. Duplications incur more prep kits than necessary.
 
  +
*'''Arrays are not allowed in the context of JSON files as resource bundles'''. String references in the code, from an i18n point of view, is unmanageable for JSON arrays. In addition, many L10n vendors do not support JSON arrays. (Sample JSON files are located in LRM-Server-2.1/''samples/JSON_Examples''):
 
  +
Sample JSON files are located in '''<HOME>/lingoport/lrm-server-x.y/samples/JSON_Examples'''.
* '''There is only one key/value per line.'''
 
  +
**Valid
 
***<code>"key1":"This is my value for key1",
+
===There is only one key/value per line===
  +
*Valid
***"key2":"This is my value for key2"</code>
 
  +
"key1":"This is my value for key1",
** Invalid
 
***<code>"key1":"This is my value for key1","key2":"This is my value for key2"</code>
+
"key2":"This is my value for key2"
  +
*Invalid
* <b>End-object character (curly bracket) may not exist on the same line as a key/value</b>.
 
  +
"key1":"This is my value for key1","key2":"This is my value for key2"
** Valid
 
  +
===End-object character (curly bracket) may not exist on the same line as a key/value===
***<code>"keys": {
 
  +
* Valid
***"key1":"This is my value for key1"
 
  +
"keys": {
***}</code>
 
  +
"key1":"This is my value for key1"
**Invalid
 
  +
}
***<code>"keys": {
 
  +
* Invalid - note bracket on same line as key/value
***"key1":"This is my value for key1"</code>'''}'''
 
  +
"keys": {
* <b>Values associated with a key must be a string</b>. Numeric and boolean values are not allowed.
 
  +
"key1":"This is my value for key1" }
** Valid
 
  +
***"key1":"0"
 
  +
===Values associated with a key must be a string===
** Invalid
 
  +
Numeric and boolean values are not allowed
***"key1":0
 
  +
* Valid
***"key1": true
 
  +
"key1":"0"
  +
* Invalid
  +
"key1":0
  +
"key1": true
  +
  +
== Example of Project Definition for Resources ==
  +
The following is an example of json resource file definitions. See [[Supported_Resource_Bundles#Resource_Extensions| resource extensions]] for more information.
  +
  +
<resource-extensions>
  +
<resource-extension>
  +
'''&lt;!-- parser-type not needed since .json is a standard LRM extension that maps to the json parser type --&gt;'''
  +
'''<extension>json</extension>'''
  +
'''<file-name-pattern>*_l-c-v</file-name-pattern>'''
  +
'''<use-pattern-on-dflt-locale>1</use-pattern-on-dflt-locale>'''
  +
'''<file-location-pattern/>'''
  +
'''<use-location-pattern-on-dflt-locale>0</use-location-pattern-on-dflt-locale>'''
  +
'''<base-file-encoding>UTF-8</base-file-encoding>'''
  +
'''<localized-file-encoding>UTF-8</localized-file-encoding>'''
  +
'''<parameter-regex-pattern><![CDATA[\{\w+\}|%[ds]]]></parameter-regex-pattern>'''
  +
</resource-extension>
  +
<resource-extension>
  +
'''''&lt;!-- parser-type is required because .myext is not a standard LRM extension --&gt;'''''
  +
'''<extension>''myext''</extension>'''
  +
'''''<parser-type>json</parser-type>'''''
  +
'''<file-name-pattern>*_l-c-v</file-name-pattern>'''
  +
'''<use-pattern-on-dflt-locale>1</use-pattern-on-dflt-locale>'''
  +
'''<file-location-pattern/>'''
  +
'''<use-location-pattern-on-dflt-locale>0</use-location-pattern-on-dflt-locale>'''
  +
'''<base-file-encoding>UTF-8</base-file-encoding>'''
  +
'''<localized-file-encoding>UTF-8</localized-file-encoding>'''
  +
'''<parameter-regex-pattern><![CDATA[\{\w+\}|%[ds]]]></parameter-regex-pattern>'''
  +
</resource-extension>
  +
</resource-extensions>

Latest revision as of 20:26, 18 September 2017

LRM supports those .json files which makes sense for translation. Not all .json files do. The JSON extension as well as file extensions using the json parser type are supported in Lingoport Resource Manager (LRM). Well-formed JSON is required and specified by http://www.ietf.org/rfc/rfc4627.txt. In order to detect and import changes,

Example of JSON files or file extensions using the json parser type

Simple JSON object

{
"the_cat": "The Cat has changed",
"the_dog": "The dog",
"the_bird": "The bird"
}

Another form of the simple JSON file

{
"the_cat":
"The Cat",
"the_dog": "The dog",
"the_bird":
"The bird has flown"
}

JSON objects

{
"the_cat": "The Cat",
"vehicles": {
       "car": "Auto",
       "bike": "Bike has changed"
},
"colors": {
       "blue": "Blue",
       "red": "Red"
}
}

JSON nested objects

{
"the_cat": "The Cat",
"dogs": {
       "pitbull": "A pitbull",
       "collie": "A collie",
       "small_dogs": {
               "poodle": "A teacup poodle"
       }
  }
}

Although JSON files do not support comments, LRM has created a way to be able to add a comment to a json file in order to work with prep-kits. The config_lrm_info.properties file, which is a group level file, sets the character that denotes a comment. The default pattern is a line that starts with '_':

### JSON Comment Pattern ###
json.comment.starts.with=_

So a comment can be added to a JSON file like:

{
"the_cat": "The Cat hates mice",
"the_dog": "The dog",
"_comment": "This comment key is defined in file 'config_lrm_info.properties' located in L10nStreamlining.",
"the_bird": "The bird"
}

A sample config_lrm_info.properties file can be found in <HOME>/lingoport/lrm-server-x.y/deploy/templates/dir_structure/group/config.


Simple is Best

A file with one key value per line, with some possible semantics in the key, is the preferred way to have .json resource files. There is no structure (no objects) to the file, so changing keys, moving them around, does not affect whatever outstanding translation will be returned at a later date with a different structure.

resources_en.json
{
 "site_heading": "Where can I find more information on the site?",
 "site_subHeading2": "Search",
 "enableGeo": "Enable location services in your browser to load local help results.",
 "findButton": "Find",
 "gettingStarted_title": "Getting Started",
 "gettingStarted_subHeading": "Here are the main things you need to know as you
get started.",
 "logging_off_account": "Log off"
}

If you want complexity

Caveat JSON structure changes can lead to problems with project on-boarded for file deltas (v. Full Files).

json parser type

valid json syntax

Files that use the json parser are expected to have valid json syntax

.json uses the json parser type

When defining a project containing LRM Standard .json resource files, there is no need to define a <parser-type> as the json parser will always be used.

unique file extension needs to define json parser type

If a unique file extension is a valid json file, then the <parser-type> should be json in the project definition file.

In what format should JSON Files or files extensions using the json parser type be for LRM Handling ?

Arrays are not allowed in the context of JSON files as resource bundles

String references in the code, from an i18n point of view, is unmanageable for JSON arrays. In addition, many L10n vendors do not support JSON arrays.

Sample JSON files are located in <HOME>/lingoport/lrm-server-x.y/samples/JSON_Examples.

There is only one key/value per line

  • Valid
 "key1":"This is my value for key1",
 "key2":"This is my value for key2"
  • Invalid
 "key1":"This is my value for key1","key2":"This is my value for key2"

End-object character (curly bracket) may not exist on the same line as a key/value

  • Valid
 "keys": {
  "key1":"This is my value for key1"
 }
  • Invalid - note bracket on same line as key/value
 "keys": {
     "key1":"This is my value for key1" }

Values associated with a key must be a string

Numeric and boolean values are not allowed
  • Valid
 "key1":"0"
  • Invalid
 "key1":0
 "key1": true

Example of Project Definition for Resources

The following is an example of json resource file definitions. See resource extensions for more information.

 <resource-extensions>
   <resource-extension>
     <!-- parser-type not needed since .json is a standard LRM extension that maps to the json parser type -->
     <extension>json</extension>
     <file-name-pattern>*_l-c-v</file-name-pattern>
     <use-pattern-on-dflt-locale>1</use-pattern-on-dflt-locale>
     <file-location-pattern/>
     <use-location-pattern-on-dflt-locale>0</use-location-pattern-on-dflt-locale>
     <base-file-encoding>UTF-8</base-file-encoding>
     <localized-file-encoding>UTF-8</localized-file-encoding>
     <parameter-regex-pattern><![CDATA[\{\w+\}|%[ds]]]></parameter-regex-pattern>
   </resource-extension>
   <resource-extension>
     <!-- parser-type is required because .myext is not a standard LRM extension -->
     <extension>myext</extension>
     <parser-type>json</parser-type>
     <file-name-pattern>*_l-c-v</file-name-pattern>
     <use-pattern-on-dflt-locale>1</use-pattern-on-dflt-locale>
     <file-location-pattern/>
     <use-location-pattern-on-dflt-locale>0</use-location-pattern-on-dflt-locale>
     <base-file-encoding>UTF-8</base-file-encoding>
     <localized-file-encoding>UTF-8</localized-file-encoding>
     <parameter-regex-pattern><![CDATA[\{\w+\}|%[ds]]]></parameter-regex-pattern>
   </resource-extension>
 </resource-extensions>