XLIFF 1.2 Representation Guide for ICU Resource Bundles

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

1.2 Transitional and Strict

XLIFF is specified in two "flavors". Indicate which of these variants you are using by selecting the appropriate schema. The schema may be specified in the XLIFF document itself or in an OASIS catalog. The namespace is the same for both variants. Thus, if you want to validate the document, the tool used knows which variant you are using. Each variant has its own schema that defines which elements and attributes are allowed in certain circumstances.

As newer versions of XLIFF are approved, sometimes changes are made that render some elements, attributes or constructs in older versions obsolete. Obsolete items are deprecated and should not be used even though they are allowed. The XLIFF specification details which items are deprecated and what new constructs to use.

• Transitional - Applications that produce older versions of XLIFF may still use deprecated items. Use this variant to validate XLIFF documents that you read. Deprecated elements and attributes are allowed.

  xsi:schemaLocation='urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-transitional.xsd'

• Strict - All deprecated elements and attributes are not allowed. Obsolete items from previous versions of XLIFF are deprecated and should not be used when writing new XLIFF documents. Use this to validate XLIFF documents that you create.

  xsi:schemaLocation='urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-strict.xsd'

An ICU Resource Bundle is a collection of resources. There are two main types of ICU resources: simple and complex. Simple resources each contain a single piece of data. There are five types of simple resources: string, integer, integer vector, binary and alias. Complex resources contain other simple and complex resources. There are two types of complex resources: table and array.

An ICU Resource Bundle consists of a top-level table resource containing all the resources in the bundle. It is recommended that the name of this bundle be the locale name. The name might also be the application name followed by _ followed by the locale name, but the first form is preferred.

ICU Resource bundles are specified in a text file. A resource is specified by a name followed by a type name and then the resource data enclosed in { and }.  The following table shows how to specify each resource type:

Resource Type	Type Name	Resource Data
string	:string	a text string optionally enclosed in quotes
integer	:integer or :int	a decimal or hexadecimal integer
integer vector	:intvector	a comma separated list of integers
binary	:binary or :bin	a sequence of hexadecimal digits optionally enclosed in quotes
alias	:alias	a path enclosed in quotes
table	:table	one or more named resources
array	:array	one or more unnamed resources separated by commas

(Notice that all type names start with a colon.)

The following is a detailed explanation of how each resource type is represented in the text file.

2.1 String Resources

String resources are represented by a sequence of Unicode characters, optionally enclosed in quotes. The string must be enclosed in quotes if it's empty or if it contains whitespace characters or any of these special characters: " : , { }.  If the string is not not enclosed in quotes, it is simply a sequence of non whitespace characters.

The string can contain the following escape sequences:
 

Escape	Followed By	Represents
\u	four hex digits	a 16 bit Unicode code point
\U	eight hex digits	a 32 bit Unicode code point
\x	two hex digits	a Unicode code point between U+0000 and U+00FF
\x{	one to eight hex digits then }	a Unicode code point
\	one to three octal digits	a Unicode code point between U+0000 and U+00FF
\c	any character	a control code (low-order four bits of character's code point)
\a		ASCII audible alert  (U+0007)
\b		ASCII backspace (U+0008)
\e		ASCII escape (U+001B)
\f		ASCII form feed (U+000C)
\n		ASCII newline (U+000A)
\r		ASCII carriage return (U+000D)
\t		ASCII tab (U+0009)
\v		ASCII vertical tab (U+000B)
\	any other character	the character (e.g. \\, \", \})

Here are some example string resources:

quoted_string :string {
    "This is a simple quoted string."
}

unquoted_string :string {
    Supercalifragilisticexpialidocious
}

string_with_escapes :string {
    "The ideograph for \"sun\" is \u65E5."
}

A string resource can be composed of multiple strings separated by whitespace characters. Quoted strings are simply concatenated together. For example, the following two definitions produce the same resource:

only_a_test :string {
    "This is "
    "only a test."
}

only_a_test :string {
    "This is only a test."
}

If the strings are not quoted, they are concatenated with a space between them. Again, the following two definitions produce the same resource:

only_a_test :string {
    This
    is
    only
    a
    test.
}

only_a_test :string {
    This is only a test.
}

(Note that in this example, each word is actually a separate string.)

This method of specifying string should not be used for language that are written without spaces because the concatenation will add spaces to the string.

String resources may contain variable data represented by a special descriptor enclosed in { and }. The variable data is supplied at runtime using the ICU MessageFormat and ChoiceFormat interfaces. Consult the ICU User Guide for more information about these interfaces. If MessageFormat or ChoiceFormat descriptors are present then either the string must be quoted or the { and } must be escaped.

(Note: ChoiceFormat messages are difficult to translate without a detailed knowledge of their syntax. For this reason, it is recommended that their use be avoided.)

String resources can also be specified indirectly using the type name :include and a string value that is the name of a file containing the string resource data. The string resource data in this file can contain the same escape sequences as a regular string resource.

2.2 Integer Resources

An integer resource is specified by a sequence of decimal digits or by 0x followed by a sequence of hexadecimal digits. A negative value is preceded by a minus sign. The value is a 32 bit signed value. Here are some examples of integer resources:

window_height :integer {
    600
}

window_offset :integer {
    -200
}

checksum :integer {
    0xBCFE3759
}

2.3 Integer Vector Resources

An integer vector is specified by a sequence of integer values separated by commas. Each integer value is specified the same way that integer resources are specified. The last value may be followed by a comma. The vector may contain a single value, multiple values, or it may be empty. Here are some examples of integer vector resources:

font_sizes :intvector {
    8,
   10,
   12,
   18,
   24,
   36
}

single_font_size :intvector {
    12
}

empty :intvector {
}

2.4 Binary Resources

A binary resource represents a chunk of binary data. It is represented by a sequence of hexadecimal digits, optionally enclosed in quotes. There must be an even number of digits. Quotes must be used to specify an empty resource. For example:

md5_sum :binary {bcfe765be0fdfab22c5f9efd12c52abc}

Binary resources can be specified indirectly using the type name :import and a quoted path for file containing the binary data. For example:

logo :import {"logo.gif"}

2.5 Alias Resources

An alias resource is a reference to another resource, possible in a different Resource Bundle. The reference is specified as a path in quotes. For example:

authors :alias {"root/authors"}

(Note: in general an alias resource that's used in one Resource Bundle may not be appropriate in another Resource Bundle. For this reason the use of alias resources be avoided.)

2.6 Table Resources

A table resource contains one or more named resources, including array resources and other table resources. The contained resources can be any type and are accessed by name. The top-level resource in an ICU Resource Bundle is a table resource that contains all of the resources in the bundle. The name of this resource is a locale name. Here are some examples of table resources:

primary_colors :table {
    red    :string {"Red"}
    orange :string {"Orange"}
    yellow :string {"Yellow"}
    green  :string {"Green"}
    blue   :string {"Blue"}
    indigo :string {"Indigo"}
    violet :string {"Violet"}
}

fonts :table {
    default_size :integer {12}

    font_sizes :intvector {
        8,
       10,
       12,
       16,
       24,
       36
    }

    font_families :array {
        :string {"Times"},
        :string {"Helvetica"},
        :string {"Courier"}
    }
}

2.7 Array Resources

An array resource contains a sequence of unnamed resources, separated by commas. The contained resources are accessed by index rather than by name. Here are some examples of array resources:

file_menu_items :array {
    :string {"Cut"},
    :string {"Copy"},
    :string {"Paste"},
    :string {"Delete"}
}

fonts :array {
    :integer {12},

    :intvector {
        8,
       10,
       12,
       16,
       24,
       36
    },

    :array {
        :string {"Times"},
        :string {"Helvetica"},
        :string {"Courier"}
    }
}

If the array contains all string resources, they can be specified without the :string type name or the enclosing { and }. For example:

fish :array {
    "One fish",
    "Two fish",
    "Red fish",
    "Blue fish"
}

2.8 Implied Resource Types

If a type name is not given, the type is determined by looking at what follows the {. A resource name followed by a type name or a { means that the resource is a table. A type name or a { means that the resource is an array. A string followed by a comma means that the resource is an array of strings. A string followed by a } means that the resource is a string. Here are some examples of resources with implied types:

color_table {
    red    :string {"Red"}
    orange :string {"Orange"}
    yellow :string {"Yellow"}
    green  :string {"Green"}
    blue   :string {"Blue"}
    indigo :string {"Indigo"}
    violet :string {"Violet"}
}

file_menu_array {
    :string {"Cut"},
    :string {"Copy"},
    :string {"Paste"},
    :string {"Delete"}
}

fish_string_array {
    "One fish",
    "Two fish",
    "Red fish",
    "Blue fish"
}

2.9 Comments

The text file can also contain C++ style comments. That is, single-line comments that start with // and extend to the end of the line, and multi-line comments that start with /* and end with */. Here are some examples of comments:

/*
 * The resources for a fictitious Hello World application. The application
 * displays a single window with a logo and the hello message.
 */
sample :table {
 ....
}

// The names of
// the translators
translators :array {
    "John E. English",
    "Alan Smithee"
}

checksum :integer { // a CRC checksum of
    0xBCFE3759      // the application binary
}

Comments that start with /** and end with */are documentation comments These comments apply to the following resource and may contain two special tokens. The token @translate instructs the translator whether or not the resource should be translated. The token @notebegins a special note to the translator. All of the comment text following these tokens up to the end of the comment or the next @, is associated with the token. It is not necessary to have whitespace after the token. Leading and trailing whitespace and * characters are ignored. Here are some examples of documentation comments:

/**
 * The names of the translators.
 *
 * @note replace these with your names.
 */
translators :array {
    "John E. English",
    "Allen Smythee"
}

/**
 * The width of the application window.
 *
 * @translate yes
 * @note Be sure that the window is
 *       wide enough to contain the
 *       translated greeting.
 */
window_width :integer {
    600
}

/**
 * The height of the application window
 *
 * @translate yes
 * @noteThere is no space after the token!
 */
window_height :integer {
    400
}

2.10 Sample ICU Resource Bundle

Here is a sample ICU Resource Bundle containing the English resources for a fictitious Hello World application. For clarity all resource type names have been specified.

/**
 * The resources for a fictious Hello World application. The application
 * displays a single window with a logo and the hello message.
 */
en :table {
    /**
     * @note This is the message that the application displays to the user.
     */
    hello :string {"Hello, world!"}

    /**
     * The height of the application window.
     *
     * @note Make sure this is tall enough to display the translated message.
     */
    window_height :integer {200}

    /**
     * The width of the application window.
     *
     * @note Make sure this is wide enough to display the translated message.
     */
    window_width :integer {600}

    /**
     * The application version number
     *
     * @translate no
     */
    version :intvector {
        1,  // major version
        2,  // minor version
        3   // patch level
    }

    /**
     * The MD5 checksum of the application.
     *
     * @translate no
     */
    md5_sum :binary {bcfe765be0fdfab22c5f9efd12c52abc}

    /**
     * The logo to be displayed in the application window.
     *
     * @translate no
     */
    logo :import {"logo.gif"}

    /*
     * The Authors. Just use the name from the root bundle.
     */
    authors :alias {"root/authors"}

    /*
     * The translators.
     */
    translators :array {
        :string {"John E. English"},
        :string {"Alan Smithee"},
        :string {"Allen Smythee"}
    }


    /**
     * The application menus.
     *
     * @note Keep the menus and the menu items in this order.
     */
    menus :table {
        file_menu :table {
            name :string {"File"}

            items :array {
                :string {"New"},
                :string {"Open..."},
                :string {"Save"},
                :string {"Save As..."},
                :string {"Exit"}
            }
        }

        edit_menu :table {
            name :string {"Edit"}

            items :array {
                :string {"Cut"},
                :string {"Copy"},
                :string {"Paste"},
                :string {"Delete"}
            }
        }

        help_menu :table {
            name :string {"Help"}

            items :array {
                :string {"Help Topics"},
                :string {"About Hello World"}
            }
        }
    }
}

This section discusses the general considerations to take in account when extracting data from ICU Resource Bundles.  The ICU genrb tool can Resource Bundle source files to XLIFF files. The ICU4J XLIFF2ICUConverter tool converts XLIFF files to ICU Resource Bundle source files. For consistency, these tools should be used whenever possible.

<?xml version="1.0" encoding="utf-8"?>
<xliff version='1.2' xmlns='urn:oasis:names:tc:xliff:document:1.2'
        xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
        xsi:schemaLocation='urn:oasis:names:tc:xliff:document:1.2 xliff-core-1.2-transitional.xsd'>
    <file xml:space = "preserve" source-language = "en" datatype = "x-icu-resource-bundle"
            original = "en.txt" date = "2007-04-11T19:03:09Z">
        <header>
            <tool tool-id = "genrb-3.3-icu-3.7.1" tool-name = "genrb"/>
        </header>
        <body>
            <group id = "en" restype = "x-icu-table">
                ... the resources in the resource bundle...
            </group>
        </body>
    </file>
</xliff>

Each ICU Resource Bundle file maps to one XLIFF <file> element. XLIFF representations of ICU Resource Bundle files should have the datatype attribute with a value of "x-icu-resource-bundle", and the original attribute set to the name of the Resource Bundle file from which the data was extracted.

The <file> element should have an xml:space attribute with a value of "preserve", establishing this as the default for the whole file. Filters should retain the whitespace in individual resources.

The optional XLIFF <header> element contains a <tool> element which identifies the tool that extracted the data from the ICU Resource Bundle.

The XLIFF <body> element contains translation units, which may be grouped using hierarchical <group>elements to represent table and array resources. Since the top-level resource in a Resource Bundle is a table resource, all of the resources in the file will be inside of a <group> element.