XLIFF Profile for Java Resource Bundles

Preliminary Working Draft - May 2006

This version:: <not applicable yet>

Latest version:: <not applicable yet>

Previous version:: <not applicable yet>

Editors:: Tony Jewtushenko<tony.jewtushenko@productinnovator.com>
: John Reid
: Rodolfo M. Raya<rmraya@heartsome.net>

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Abstract

This document describes how Java Resource Bundles (List Resource Bundles and Property Resource Bundles) should be coded when extracted to an XLIFF document.

Status of this Document

This document is a Preliminary Working Draft of the committee. It is an OASIS draft document for review by OASIS members and other interested parties. Comments may be sent to xliff-comment@lists.oasis-open.org.

This document may be updated, replaced, or rendered obsolete by other documents at any time. It may also be discarded without further follow up. It is inappropriate to use this document as reference material other than "work in progress".

1. Introduction
          1.1. Purpose
2. General Considerations
          2.1.   Java Resource Types
          2.2.   ListResourceBundle
          2.3.   PropertyResourceBundle
          2.4.   Extraction Techniques
          2.5.   Order Of Extraction
          2.6.   Key Identifier
          2.7.   Preserving Message Replaceables in Value
          2.8.   Comments
          2.9.   Sample Properties File represented as XLIFF
          2.10 Sample List Resources Java Class represented as XLIFF

1. Introduction

As different tools may provide different filters to extract the content of Java Resource Bundles, it is important for interoperability that they represent the extracted data in identical manner in the XLIFF document.

1.1. Purpose

The intent of this document is to provide a set of guidelines to represent data contained in Java Resource Bundles as XLIFF content. It offers a collection of recommended mapping of Java Resource Bundles that developers of XLIFF filters can implement, and users of XLIFF utilities can rely on to insure a better interoperability between tools.

2. General Considerations

This section discusses the general considerations to take in account when extracting Java Resource Bundle data.

2.1. Java Resource Types

Java's architecture supports the localisation of application resources via the java.util.ResourceBundle abstract class. This class has two subclasses: PropertyResourceBundle and ListResourceBundle. A ResourceBundle contains key/value pairs, where each key uniquely identifies locale-specific objects in the bundle. Non-string resources, binary objects, must be stored in ListResourceBundles, since the PropertyResourceBundle can only contain String objects. String values can contain MessageFormat replaceables, which are delimited within {}.

2.2. ListResourceBundle

A ListResourceBundle is a list of resources stored in a .class file. Compiled resources are stored in binary format, which means ListResourceBundle can contain localised resources of any data type.

Additional locales are created by copying the base .java file to a locale specific .java file identified by adding a locale suffix to its filename. After translation has been completed, the localized .java file is compiled into a .class file.

Listing 1 shows a sample ListResourceBundle class named "MyResources.java" and a version for "fr" locale.

 
 public class MyResources extends ListResourceBundle {
     public Object[][] getContents() {
         return contents;
     }
     static final Object[][] contents = {
     // LOCALIZE THIS
         {"s1", "The disk \"{1}\" contains {0}."},  // MessageFormat pattern
         {"s2", "1"},                               // location of {0} in pattern
         {"s3", "My Disk"},                         // sample disk name
         {"s4", "no files"},                        // first ChoiceFormat choice
         {"s5", "one file"},                        // second ChoiceFormat choice
         {"s6", "{0,number} files"},                // third ChoiceFormat choice
         {"s7", "3 Mar 96"},                        // sample date
         {"s8", new Dimension(1,5)}                 // real object, not just string
     // END OF MATERIAL TO LOCALIZE
     };
 }

 public class MyResources_fr extends ListResourceBundle {
     public Object[][] getContents() {
         return contents;
     }
     static final Object[][] contents = {
     // LOCALIZE THIS
         {"s1", "Le disque \"{1}\" {0}."},          // MessageFormat pattern
         {"s2", "1"},                               // location of {0} in pattern
         {"s3", "Mon disque"},                      // sample disk name
         {"s4", "ne contient pas de fichiers"},     // first ChoiceFormat choice
         {"s5", "contient un fichier"},             // second ChoiceFormat choice
         {"s6", "contient {0,number} fichiers"},    // third ChoiceFormat choice
         {"s7", "3 mars 1996"},                     // sample date
         {"s8", new Dimension(1,3)}                 // real object, not just string
     // END OF MATERIAL TO LOCALIZE
     };
 }

Listing 1 - Sample List Resource file

2.3. PropertyResourceBundle

PropertyResourceBundle is a concrete implementation of ResourceBundle class that stores translatable String resources in plain text files via name-value pairs using "name=value" syntax.

The resources of a PropertyResourceBundle are stored in files with the extension ".properties". Properties files strings are fetched at run-time, they are not compiled. The keys are case-sensitive and should be unique within the .properties file.

Listing 2 below is a sample PropertyResourceBundle .properties file with two localizable strings.

#The following resource is written in two lines.
template = At {2,time,short} on {2,date,long}, we detected \
{1,number,integer} spaceships on the planet {0}.
planet = Mars // Inline comment

Listing 2 - Sample .properties file

2.4.Extraction Techniques

Resource Bundles are Java code and not XML. Therefore, XSL transformation standards cannot be utilized to convert the resource bundles into XLIFF. XSLT could be used to transform the translated XLIFF back to the native Java, or to manipulate an intermediate XML or initial XLIFF file in preparation for manual or automated Computer Aided Translation (CAT), but software best practices favour using the same technology for both extraction and recomposition.

2.4.1. Using Filters

It is necessary to extract the Java Resource Bundles- List and Property - to XLIFF by developing a custom filter application. Such tools can be written using a variety of programming and scripting languages such as Perl, Python, C, C++, C#, Java, etc..

This document makes no assumption on the type of language used to process the Java Resource Bundle input documents. It also makes no assumptions whether or not the tool creates a Skeleton file along with the XLIFF document generated, or if it creates one, how data are represented in the Skeleton.

2.5. Order of Extraction

The flow of the extracted data in the XLIFF document should be in the same order as the flow of data in the original Resource Bundle. The extraction order should reflect the order of the data in the source document, and the author is responsible to group logical parts of the text together as much as possible.

The following guidelines should be adhered to:

Each .properties file is represented in a separate <file> element in an XLIFF document
The datatype attribute of a <file> element is set to javapropertyresourcebundle or javalistresourcebundle, depending on the type of resource
The <body> element contains a separate <trans-unit> element for each key-value pair
The translate attribute of <trans-unit> element is set to no when the value string is a null string
The value string becomes the content of the child <source> element

2.6. Key Identifier

The identifier used for matching, leveraging, and other ID-related functions is stored in the resname attribute. The key of the resource becomes the resname attribute value of the <trans-unit> element.

The required id attribute of the XLIFF <trans-unit> element is an identifier allowing extraction tools to merge back the data. The value of the id attribute is serially assigned, according the retrieval order, to maintain consistency and uniqueness.

2.7. Preserving Message Replaceables in Value

Variable data is represented in Java strings using special descriptors surrounded by { and }. Those descriptors, called "replaceables", are processed by the MessageFormat class at run-time to display variable data in the appropriate format for the selected locale. MessageFormat replaceables should be enclosed in <ph> elements by the filter that generates the XLIFF representation. If Skeleton files are used, a replaceable can optionally be represented with an <x/> tag instead of a <ph> element.

Although most of the XLIFF inline tags are represented in the TMX Standard, the <x/> tag is not. TMX is a standard to exchange Translation Memory (TM) data created by Computer Aided Translation (CAT) and localization tools. If you plan to store or deliver XLIFF text content using TMX, you may wish to use <ph> elements for encapsulating replaceables. Otherwise, you will need to represent <x/> tags in some alternate way in TMX.

2.8. Comments

There are two kinds of comments in Property resources:

Lines that start with a # character. These lines do not contain translatable text. Filter designers may optionally concatenate consecutive lines starting with a # character and include them as context information in one <note> element in the first <trans-unit> generated after extracting the comments.
Text following // characters. All text appearing between two consecutive backslashes and the end of the line is considered a comment and does not need to be localized. When this kind of comment appears in a line containing a key/value pair, the comment should be included in a <note> element in the <trans-unit> generated for the key/value pair. If this kind of comment is not part of a line with translatable text, it should be treated as a line starting with a # character.

Comments in classes derived from ListResourceBundle are subject to Java coding rules. If an XLIFF filter tool finds comments inside a run of localizable text in a List resource, the comment should be preserved by being treated as inline code and enclosed in a <ph> element. If Skeleton files are used, the comment can optionally be represented with an <x/> tag instead of a <ph> element.

In List resources, if an XLIFF filter finds comments following a key value pair, the comments should be associated with the corresponding <trans-unit> element using a <note>.

2.9 Sample Properties File represented as XLIFF:

Listing 3 belows contains the XLIFF representation of the .properties file shown in Listing 2.

<?xml version="1.0"?>
    <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en-US" datatype="javapropertyresourcebundle"
        original="MessageBundle_en_US.properties">
    <body>
      <trans-unit id="1" restype="string" resname="template">
        <source>At <ph id="1">{2,time,short}</ph> 
          on <ph id="2">{2,date,long}</ph>, we detected 
          <ph id="3">{1,number,integer}</ph> spaceships 
          on the planet <ph id="4">{0}</ph>.</source>
        <note>#The following resource is written in two lines.</note>
      </trans-unit>
      <trans-unit id="2" restype="string" resname="planet">
        <source>Mars</source>
        <note>// Inline comment</note>
      </trans-unit>
    </body>
  </file>
</xliff>

Listing 3 - XLIFF representation of a .properties file

2.9 Sample List Resources Java Class represented as XLIFF:

Listing 4 shows the XLIFF document with localizable data extracted from the class "MyResources.java" included in Listing 1.

<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
 <file source-language="en-US" datatype="javalistresourcebundle" original="MyResources.java">
  <body>
   <trans-unit id="1" restype="string" resname="s1">
     <source>The disk <ph id="1">\"{1}\"</ph> contains <ph id="2">{0}</ph>.</source>
     <note>// MessageFormat pattern</note>
   </trans-unit>
   <trans-unit id="2" restype="string" resname="s2">
     <source>1</source>
     <note>// location of {0} in pattern </note>
   </trans-unit>
   <trans-unit id="3" restype="string" resname="s3">
     <source>My Disk</source>
     <note>// sample disk name</note>
   </trans-unit>
   <trans-unit id="4" restype="string" resname="s4">
     <source>no files</source>
     <note>// first ChoiceFormat choice</note>
   </trans-unit>
   <trans-unit id="5" restype="string" resname="s5"> 
     <source>one file</source>
     <note>// second ChoiceFormat choice</note>
   </trans-unit>
   <trans-unit id="6" restype="string" resname="s6"> 
     <source><ph id="1">{0,number}</ph> files</source>
     <note> // third ChoiceFormat choice</note>
   </trans-unit>
   <trans-unit id="7" restype="string" resname="s7">
     <source>3 Mar 96</source>
     <note>//sample date</note>
   </trans-unit>
   <trans-unit id="8" restype="string" resname="s8">
     <source>new Dimension(1,5)</source>
     <note> // real object, not just string</note>
   </trans-unit>
  </body>
 </file>
</xliff>

Listing 4 - XLIFF representation of a List Resource Bundle

A. Contributions

The following people have contributed to this document:

Eiju Akahane, IBM
Doug Domeny
Tony Jewtushenko, Oracle
Milan Karásek, Moravia-IT
Christian Lieske, SAP
Mat Lovatt, Oracle
Magnus Martikainen, TRADOS
David Pooley, SDL
Rodolfo M. Raya, Heartsome
John Reid, Novell
Peter Reynolds, Bowne Global Solutions
Bryan Schnabel, Tektronix
Shigemichi Yazawa
Andrzej Zydron, XML-Intl

B. References

[ISO]: International Organization for Standardization Web site.
[Java]: Core Java Internationalization Web Site; Documentation of ResourceBundle Class

[OASIS]: Organization for the Advancement of Structured Information Standards Web site.

[RFC 3066]: RFC 3066 Tags for the Identification of Languages. IETF (Internet Engineering Task Force), Jan 2001.
[Unicode]: Unicode Consortium Web site.