LRM XML Support

From Lingoport Wiki
Jump to: navigation, search

Formatting xml files

LRM uses the xmlParser.xml file to parse any extensions that have a xml parser type. This file is located in the

  ~jenkins/Lingoport_Data/L10nStreamlining/<group>/projects/<project>/config folder.

XML Parser Syntax

The xmlParser.xml directs LRM on the location of the keys and values within the xml files as well as whether the key/value is translatable. The xml syntax is defined by 3 tokens:

  • TOKEN_KEY is required and can be defined as either an attribute or a text node. For example:
    • <data>TOKEN_KEY</data>
    • <entry name="TOKEN_KEY"></entry>
  • TOKEN_TRANSLATABLE is optional and can only be defined as an attribute. For example:
    • <key name="TOKEN_KEY" istrans="TOKEN_TRANSLATABLE"></key>
  • TOKEN_VALUE is required and can only be defined as a text node. For example:
    • <value>TOKEN_VALUE</value>

Limitations of XML Definition

There are structural limitations to xml files that can be parsed by LRM.

  • The element containing the key must be before the value element. For example, the following is an xml file that cannot be parsed by LRM:
<?xml version='1.0' encoding='utf-8'?>
<!-- xml file that cannot be parsed by LRM because the value is before the key -->
<root>
  <entry>
    <value>This is the value for key1</value>
    <key>key1</key>
  </entry>
  <entry>
    <value>This is the value for key2</value>
    <key>key2</key>
  </entry> 
</root>
  • The keys and values can only be defined by, at most, one element each. For example, the following is a xml file that cannot be parsed by LRM:
<?xml version='1.0' encoding='utf-8'?>
<!-- xml file that cannot be parsed by LRM because the key/values are 
   contained within both the data and the key elements -->
 <root>
   <entry>
      <data name="key1">Value for key 1</data>
   </entry>
   <entry>
      <key name="key2">Value for key 2</key>
   </entry> 
 </root>
  • If there is a flag that indicates whether the key should be translated, then this flag must be an attribute of either the key element or the value element. For example, the following is a xml file that cannot be parsed by LRM:
 <?xml version='1.0' encoding='utf-8'?>
 <!-- xml file that cannot be parsed because the isTranslatable flag is not an attribute
  of the key or value element. However, this file could be parsed if the isTranslatable flag was ignored
  in the xmlParser.xml definition   -->
 <root>
    <data name="key1">This is the value1</data>
    <info istrans="1"/>
    <data name="key2">This is the value2</data>
    <info istrans="0"/>
 </root>
  • If the key is a text node then the key and value must have a parent. For example, the following is a xml file that cannot be parsed by LRM:
 <?xml version='1.0' encoding='utf-8'?>
 <!-- xml file that cannot be parsed because the key is in the text node and there is no parent -->
 <root>
    <key>key1</key>
    <value>Value for key1</value>
    <key>key2</key>
    <value>Value for key2</value>
  </root>
  • The key and value must have the same parent element (if applicable) or the key must be the parent of the value. For example, the following is a xml file that cannot be parsed by LRM:
  <?xml version='1.0' encoding='utf-8'?>
  <!--xml file that cannot be parsed because key and value have different parent elements -->
  <root>
     <parentKey>
        <key>key1</key>
     </parentKey>   
     <parentValue>
        <value>This is a value for key 1</value>
     </parentValue>
     <parentKey>
        <key>key2</key>
     </parentKey>   
     <parentValue>
        <value>This is a value for key 2</value>
     </parentValue>
  </root>

OTB XML Parser Definitions

There are 3 out-of-the-box parser definitions for XML files.

Unique XML Parser Definitions

There are several layout combinations that can be used to define the project's unique xml files. There are examples in the ../lrm-server-x.x/samples/XmlParserExamples folder. After creating a LRM project that uses the xml parser type, copy over one of the examples into the ../L10nStreamlining/<group>/projects/<project>/config folder, rename it to xmlParser.xml and change the structure to represent the project's xml files.

AndroidParser.xml structure

The AndroidParser.xml file defines the structure of Android files.

Sample Android xml file

A typical Android file has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <string name=""hello_world"" translatable=""true"">Hello World</string>
  <string name=""goodbye"" translatable=""true"">Good Bye</string>
</resources>

Parser definition for Android files

For Android files, the value is the text node of the element of the key attribute:

<?xml version='1.0' encoding='utf-8'?>
<resources>
  <string name="TOKEN_KEY" translatable="TOKEN_TRANSLATABLE">TOKEN_VALUE</string>
</resources>

ResxParser.xml structure

The ResxParser.xml file defines the structure of .resx xml files.

Sample Resx xml file

A typical Resx file has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <data name="hello_world"> 
    <value>Hello World</value>
  </data>
  <data name="goodbye"> 
    <value>Good Bye</value>
  </data>
 </root>

Parser definition for Resx files

For Resx files, the element of the key attribute is the parent of the value element:

<?xml version='1.0' encoding='utf-8'?>
 <root>
   <data name="TOKEN_KEY" >
     <value>TOKEN_VALUE</value>
   </data>
 </root>

RxmlParser.xml structure

The RxmlParser.xml file defines the structure of .rxml xml files.

Sample Rxml xml file

A typical Rxml file has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<properties>
   <entry key="hello_world">Hello World</entry>
   <entry key="goodbye">Good Bye</entry>
</properties>

Parser definition for Rxml files

  <?xml version="1.0" encoding="UTF-8"?>
  <properties>
    <entry key="TOKEN_KEY">TOKEN_VALUE</entry>
  </properties>

Example1: Key/Value have same element and parent

The following is an example file and parser definition where the key/value have a parent element and the value is the text node of the element for the key attribute.

Sample parentSameElement file

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <parent>
      <data key="hello_world">Hello World</data>
   </parent>
   <parent>
      <data key="goodbye">Good Bye</data>
   </parent>
</root>

Parser definition for parentSameElement files

  <?xml version="1.0" encoding="UTF-8"?>
  <root>
     <parent>
       <data name="TOKEN_KEY">TOKEN_VALUE</data>
     </parent>
  </root>

Example2: Value has own element and key/value have parent

The following is an example file and parser definition where the key/value have a parent element and they each have their own element

Sample parentValueElement file

<?xml version="1.0" encoding="UTF-8"?>
<data>
   <trans>
      <entry key="hello_world" isTranslatable="yes"/>
      <value>Hello World</value>
   </trans>
   <trans>
      <entry key="goodbye" isTranslatable="yes"/>
      <value>Good Bye</value>
   </trans>
</data>

Parser definition for parentValueElement files

  <?xml version="1.0" encoding="UTF-8"?>
  <data>
     <trans>
       <entry key="TOKEN_KEY" isTranslatable="TOKEN_TRANSLATABLE"/>
       <value>TOKEN_VALUE</value>
     </trans>
  </data>

Example3: key/value have parent and key is parent of value

The following is an example file and parser definition where each key/value pair have a parent and the key element is the parent of the value element.

Sample parentKeyParentOfValue file

  <?xml version='1.0' encoding='utf-8'?>
  <resource>
     <data>
        <key name="hello_world" trans="1">
           <value>Hello World</value>
        </key>
     </data>	
     <data>
        <key name="goodbye" trans="1">
           <value>Good Bye</value>
        </key>
     </data>
  </resource>

Parser definition for parentKeyParentOfValue files

  <?xml version='1.0' encoding='utf-8'?>
  <resource>
     <data>
        <key name="TOKEN_KEY" trans="TOKEN_TRANSLATABLE">
           <value>TOKEN_VALUE</value>
        </key>
     </data>		
  </resource>

Example4: key/value have parent and key is a text node

The following is an example file and parser definition where each key/value pair have a parent and the key element is a text node.

Sample parentKeyTextNode file

  <?xml version='1.0' encoding='utf-8'?>
  <resource>
     <data>
        <key trans="true">hello_world</key>
        <value>Hello World</value>
     </data>	
     <data>
         <key trans="true">goodbye</key>
         <value>Good Bye</value>
     </data>
  </resource>

Parser definition for parentKeyTextNode files

  <?xml version='1.0' encoding='utf-8'?>
  <resource>
     <data>
        <keytrans="TOKEN_TRANSLATABLE">TOKEN_KEY</key>
        <value>TOKEN_VALUE</value>
     </data>		
  </resource>

Invalid xmlParser.xml Examples

TOKEN_VALUE cannot be defined before TOKEN_KEY

 <?xml version='1.0' encoding='utf-8'?>
 <data>
    <value>TOKEN_VALUE</value>
    <entry>TOKEN_KEY</entry>
 </data>

Tokens cannot appear more than once in the xmlParser.xml file

 <?xml version='1.0' encoding='utf-8'?>
 <root>
    <string name="TOKEN_KEY">TOKEN_VALUE</string>
    <value>TOKEN_VALUE</value>
 </root>

TOKEN_KEY cannot have more than 1 parent

 <?xml version='1.0' encoding='utf-8'?>
 <root>
     <parent1>
        <parent2>
           <string name="TOKEN_KEY">TOKEN_VALUE</string>
         </parent2>
      </parent1>
 </root>

TOKEN_TRANSLATABLE cannot be an attribute of an non-key, non-value element

A xml file that has the isTranslatable flag set in its own element is not supported by LRM

 <?xml version='1.0' encoding='utf-8'?>
 <root>
    <data>
       <string name="TOKEN_KEY">TOKEN_VALUE</string>
       <info istrans="TOKEN_TRANSLATABLE"></info>
     </data>
 </root>

Number of elements cannot exceed 4

The only content in the xmlParser.xml is information leading to location of key/values. No other information is necessary.

 <?xml version='1.0' encoding='utf-8'?>
 <root>
    <data>
       <key>TOKEN_KEY</key>
       <string>TOKEN_VALUE</string>
       <addtlInfo></addtInfo>
     </data>
 </root>