Knowledgebase

Introduction

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

Suggested translation workflow

We suggest that developers and translators use the following workflow:

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

6. Developers use WHM's  Locale XML Upload interface (Home >> Locale >> Locale XML Upload) to import the updated locale information.

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 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].).

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:

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

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:

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