XML Parser

Contents/Quick-Jump

·	XSL Transformation Stylesheet	·	Testing an XML Parser
·	How to Create an XML Parser	·	XML Parser File Naming Convention
·	Unique Identification of Elements	·	Activating the XML Parser

See also:

·	XML Parser Examples (Overview)
·	Additional (XML) References

Introduction

This topic describes the procedure for creating an XML parser to allow a specific XML format structure to be read and written by RC-WinTrans.

XML files come in a wide variety of structures and types. XML is nothing more than a set of basic rules for organizing almost any kind of data. Therefore the only way to properly support the localization of an XML file is to accommodate the file’s specific internal structure and localizable contents.

RC-WinTrans processes (reads and writes) XML files using an XSLT transformation. An XSL style-sheet acts as a parser reading a certain XML file format and specifying which data is to be translated.

The figure above shows an XSLT transformation (2) (tool: "msxsl.exe") used to transform an XML file (1) to an XML file (4) containing the content of the XML file (1) plus instructions (3) on which elements are to be translated.

The XML parser (3) (XSL stylesheet) contains the logic to read the XML file (1) and to add instruction attributes to those elements which are translatable.

Finally, RC-WinTrans (5) reads the transformed XML file (4) and saves the translatable elements and attributes to the translation database of an RC-WinTrans translation project.

^ Top ^

XSL Transformation Stylesheet

Using an XSLT Stylesheet as an XML Parser – BaSiC Concepts

The XSL language is used to select those XML elements in an XML document that are translatable (example...).

An XML instruction attribute is added to the selected XML element to specify that the text of an element (or of an attribute) is translatable (example...).

The XSL programming is done in an XSL stylesheet (file extension = .xsl). This stylesheet is what is known as the "XML parser" (examples...).

The XSL stylesheet acts as an XML parser and is used as input for an XSLT processor to create an XML file with additional attributes specifying that elements and/or attributes are translatable.

There are two tasks which the XSL file must describe:

1.	copy elements – make a copy of the XML file (the XML file to be translated).
2.	add instruction attributes – specify those XML elements and attributes that are translatable by adding instruction attributes.

A set of RC-WinTrans XML attributes are provided to specify that an element or attribute is translatable. These attributes are added to an XML element, giving instructions on what is to be done with that element. They are called "instruction attributes" because they give RC-WinTrans instructions for handling the element.

Please refer to the "RC-WinTrans Instruction Attributes" topic for additional details.

To create your own XML parser, use the XSL template file provided with RC-WinTrans ("XMLParser-Template.XSL"; directory: "Samples" | "Developing" | "XML Parser").

See also: "XML Examples: Overview."

^ Top ^

How to Create an XML Parser

1.	Make a copy of the XML parser template file.
2.	Ascertain the name of the root element of the specific XML file structure supported by the parser.
3.	Edit the XSL file, using the RC-WinTrans XML instruction attributes to specify all translatable elements.
4.	Use the name of the root element (Step 2) to rename the template file following the naming convention for RC-WinTrans XML parser files: "XMLParser-<root element name>.XSL"

Unique Identification of Elements

The elements of an XML file to be translated should be positively identifiable so that RC-WinTrans can accurately update the database whenever changes are made to the (source) XML file and existing translation data will be preserved during the update.

Giving an element an identifier (resource name) that is unique within the XML file guarantees positive identification of that element. If an element is a child element of a group, its identifier (ID) should be unique within the parent group. The group must therefore have a resource name too.

Specifying a Resource Name

The identifier (resource name) of the three instruction attributes ("rwt:group," "rwt:elementTU," and "rwt:attributeTU_<attrName>") is specified with the respective element's value (element text).

NOTE: The resource names of groups and elements do not have to be unique- this is not a requirement for the file. It is, however, required in order to preserve existing translation data during the update database process, which updates the source information whenever changes have been made to the original (source) XML file.

^ Top ^

Testing an XML Parser

Copy the following files into one folder:

·	the "msxsl.exe" command line tool from Microsoft.
·	your XML parser file (file extension = .xsl)
·	one of the XML files for which your XML parser was created.

Run "msxsl.exe" to generate a copy of the XML file that should contain the RC-WinTrans instruction attributes for all elements that need to be translated.

Check the XML file that was created.

Once the transformed XML file has been created you can add your XML file to be translated to an RC-WinTrans project. The elements to be translated should be displayed in RC-WinTrans' Project window.

If the elements are not read and listed as expected, you will need to edit the parser again. Once this is done you can force RC-WinTrans to reread the XML file by performing the following actions:

a.	Open the Source and Target Files dialog box.
b.	Select the XML file in the display on the Source Files page.
c.	Check the Force update for unchanged source files checkbox at the bottom of the page.
d.	Press the Update (selected) button.

^ Top ^

XML Parser File Naming Convention

XML parser files (file extension =.xsl) have a predefined file naming convention. It dictates that the file name begin with the prefix "XMLParser-" followed by the name of the root element of the XML file for which the parser is made.

EXAMPLE: "XMLParser-Symbols.xsl"; "XMLParser-docroot.xsl"

NOTE: If the name of the XML root element contains a namespace then an underline character must be used in the file name for the ':' between the namespace and the root element name

EXAMPLE: root element name <mnts:materials>

XML parser file name "XMLParser-mnts_materials"

Activating the XML Parser File

Option 1: Local Folder

Place the XML parser file in the same folder as the XML files to be translated. This causes the XML parser to be used only on XML files located in the same folder.

If you're developing an XML parser, the parser file and an XML file (to be translated) will be in one folder. The XML file can be directly added to an RC-WinTrans project. RC-WinTrans will automatically use the XML parser if the parser file meets the predefined file naming convention (see above).

Option 2: General File Converters Folder

Place the XML parser file in the RC-WinTrans installation folder named "FileConverters" (<installdir>\RC-WinTrans 9\FileConverters). This causes the XML parser to be used globally for all XML files (supplied by a particular XML parser file).

RC-WinTrans will look for the XML parser file in the same folder as the one containing the XML file to be translated (local folder) first. If a converter is not found there, RC-WinTrans will check the "FileConverter" folder for the required XML parser (general file converters folder).

^ Top ^