Guide to Locales

Introduction

The locale system localizes text in Perl, Template Toolkit, or JavaScript code.

Localization refers to the translation of text in one language into multiple other languages, as well as the addition of cultural adaptations to make a product usable globally.

cPanel & WHM's locale system uses CPAN's Locale::Maketext and Locale::Maketext::Utils modules to perform the majority of its tasks. For detailed information about the module's methods and options, read CPAN's Locale::Maketext::Utils documentation.

Warning:

You cannot call the locale system directly from PHP applications. if You want localized text in your custom code, we strongly recommend that you use Perl or JavaScript, or that you display the text via a Template Toolkit file.
Custom translations may contain HTML markup which the WHM, cPanel, and Webmail interfaces render to other accounts on the system.
- To ensure that this functionality does not cause a security risk, cPanel & WHM restricts the ability to provide custom translations to resellers with the Locales ACL .
- Account restorations, backups, or transfers may install custom translations. To disable this behavior, use cPanel & WHM's Restricted Restore features .

Locales

Each locale has a lexicon hash, which contains keys and values in bracket notation. Each value is the translated version of the key (or, for the default English locale (en), values are specifically empty). Typically, the key in the lexicon hash is the phrase itself, rather than an arbitrary lookup key.

The locale system uses ISO codes from the Unicode Common Locale Data Repository (CLDR) as locale names (for example, fr for French or en_gb for British English).

Locale names for base languages may use ISO-639-1 's two-letter system, while region-specific locale names include this two-letter code, an underscore ( _ ), and the ISO-3166 two-letter standard.
en is the default locale, and en_us (American English) is an alias to en . This means that you cannot create the en_us locale separately, as you could with en_gb .
In order to prevent missing phrases in region-specific locales, we merge regional lexicons with the base language's lexicon. For example, the Mexican Spanish ( es_mx ) lexicon contains some lexicon entries from the Spanish ( es ) lexicon.

To view a list of the available locales on a cPanel & WHM server, navigate to WHM's View Available Locales interface (WHM >> Home >> Locales >> View Available Locales).

The terms "locale" and "language" are not interchangeable. Multiple locales may use the same base language but implement different conventions for specific geographical, dialectical, or cultural distinctions. For example, WebPros International, LLC provides separate locales for Spanish and Latin American Spanish.

Localization tasks

Because of its flexibility, the locale system offers the following customization options:

You can include translated phrases in custom interface templates or command line output. For more information, read our Basic Usage documentation.
You can distribute locales. For more information, read our Distribute a Custom Locale documentation.
You can delete custom locales. For more information, read our Delete a Locale documentation.

Warning:

We strongly recommend that you only create and modify locales through the WHM interface. Manual edits generally result in nonfunctional locales.