Development Guides Home >> Guide to Locales

Guide to Locales - For Translators

Introduction

This document provides information for translators of phrases from cPanel & WHM's locale system.

Suggested translation window

We suggest that developers and translators use the following workflow:

Developers write the code that uses the locale system.
Developers use WHM's Locale XML Download interface ( WHM >> Home >> Locale >> Locale XML Download ) to export a copy of the XLIFF file.
Translators use WHM's Locale XML Upload interface ( WHM >> Home >> Locale >> Locale XML Upload ) to import the XLIFF file.
Translators update the locale lexicon(s) in WHM's Edit a Locale interface ( WHM >> Home >> Locale >> Edit a Locale ).
Translators use WHM's Locale XML Download interface ( WHM >> Home >> Locale >> Locale XML Download ) to export a copy of the XLIFF file.
Developers use WHM's Locale XML Upload interface ( WHM >> Home >> Locale >> Locale XML Upload ) to import the updated locale information.

For help to distribute locale lexicons to many servers, read our Distribute a Custom Locale documentation.

The XLIFF format

XML Localization Interchange File Format (XLIFF) is an XML-based format that standardizes the way in which tools pass data. The locale system does not run on XLIFF-formatted data, but does use the format to import and export locale system data. Because of this fact, it is important to understand XLIFF files before you begin the translation process.

XLIFF Files

XLIFF files appear similar to the following example:

<xliff version='1.2' xmlns='urn:oasis:names:tc:xliff:document:1.2'>
   <file original='hello.txt' source-language='en' target-language='fr' datatype='plaintext'>
     <body>
        <trans-unit id='hi'>
          <source>Hello world</source>
          <target>Bonjour le monde</target>
        </trans-unit>
     </body>
   </file>
</xliff>

XLIFF files will contain the following elements:

file — A single extracted file and its information. The file element may contain the following additional information:
- original — The original (pre-extraction) file name.
- source-language — The <source> element's language.
- target-language — The <target> element's language.
- datatype — The original (pre-extraction) file's data type.
trans-unit — A translation unit. This element contains <source> and <target> elements:
- <source> — The phrase to translate, in the default language. For cPanel's locale system, source phrases appear in English ( en ).
- <target> — The translated phrase, in the language that the target-language element specifies.

For more information, read the XLIFF 1.2 Specification documentation.

cPanel-specific XLIFF elements

In addition to XLIFF's default elements, cPanel uses the following custom attributes in its XLIFF files:

cp:ref — A value that references another trans-unit element's id value.
- For example, a <ph> element that contains the quant() bracket notation method will also contain a cp:ref attribute.
- This cp:ref attribute references the id value for the <group> element that contains that quant() method's structure.
cp:meta-note — A string that contains metadata that may be useful to cPanel or to the translation service.
cp:replace — An internal attribute that cPanel uses to identify the original potion of a phrase to replace with the element's rendered context.
cp:lexicon-key — An internal attribute that cPanel uses to map a <source> phrase to its arbitrary key in the locale's lexicon.

Bracket notation for translators

The locale system uses bracket notation to mark the dynamic potions of translated phrases. Bracket notation is additional markup within a translated phrase, surrounded with brackets ([]).

The following examples list some of the ways in which developers might use bracket notation:

References to variables (for example, “[_1]“ is not a valid domain name. ).
Locale-specific number formatting (for example, Page [numf,_1] of [numf,_2] ).
Output-agnostic links (for example, To complete your request, [output,url,_1,click here]. ).
Locale-specific noun quantization (for example, The system will retain data for [quant,_1,day,days]. ).

For more information about bracket notation use for developers, read our Bracket Notation and Bracket Notation Methods documentation.

Example

The following bracket notation example uses the quant() method, which is common in locale system phrases. This method displays a variable amount of a resource or content (for example, memory or files).

These examples use the following localized phrase:

The system retains data for [quant,_1,day,days].

In an XLIFF file, this phrase returns the following <source> value:

The system retains data for <ph id="bn-1" ctype="x-bn-complex" assoc="both" cp:replace="[quant,_1,day,days]" cp:ref="gp-1">[quant,_1,day,days]</ph>

In English, quantities use a simple "one or other" structure.

If the value is 1 , the quant() method returns the first option ( day ).
If the value is more than 1 , the quant() method returns the second option ( days ).

This results in the following group code for the English file:

<group id="gp-248">
        <trans-unit id="gp-248-one" datatype="plaintext">
          <source><ph id="num-str-248-one" ctype="x-implied">%s</ph> day</source>
          <target><ph id="num-str-250-one" ctype="x-implied">%s</ph> day</target>
          <note>Plural category: one</note>
        </trans-unit>
        <trans-unit id="gp-248-other" datatype="plaintext">
          <source><ph id="num-str-248-other" ctype="x-implied">%s</ph> days</source>
          <target><ph id="num-str-250-other" ctype="x-implied">%s</ph> days</target>
          <note>Plural category: other</note>
        </trans-unit>
</group>

Some languages (for example, Russian) have complex rules, which result in many plural categories, and the following group code:

<group id="gp-1">
       <trans-unit id="bn-1-one" datatype="plaintext">
          <source><ph id="num-str-1-one" ctype="x-implied">%s</ph> day.</source>
          <note>Plural category: one<note>
        </trans-unit>
        <trans-unit id="bn-1-few" datatype="plaintext">
          <source><ph id="num-str-1-few" ctype="x-implied">%s</ph>days.</source>
          <note>Plural category: few</note>
        </trans-unit>
        <trans-unit id="bn-1-many" datatype="plaintext">
          <source><ph id="num-str-1-many" ctype="x-implied">%s</ph>days.</source>
          <note>Plural category: many</note>
        </trans-unit>
        <trans-unit id="bn-1-other" datatype="plaintext">
          <source><ph id="num-str-1-other" ctype="x-implied">%s</ph>days.</source>
          <note>Plural category: other</note>
        </trans-unit>
</group>