Introduction

Cpanel::Locale is a modern localization system in cPanel and WHM. This new system is easier for developers to work with and facilitates higher quality localization. The end goal of this new system is the full coverage of localization throughout WHM, cPanel, and their command-line scripts. While this new system is flexible and robust, we have made every effort to ensure it exceeds our strict resource usage efficiency standards.

Key Principles and Conventions

Remember: When editing local files, avoid using esoteric terms and phrases.

To avoid confusion, this documentation will use the following conventions:

• When referring to the old language system we will use the terms lang and legacy.
  • For example: "A legacy lang tag."
• When refering to the new language system we will use the terms locale or Cpanel::Locale.
  • For example: "A locale lexicon entry."
• Each locale has a lexicon. A lexicon is a hash whose keys (and values) are in bracket notation. The value is the translated version of the key (or, for the default en, values are specifically empty).
• Locale lexicons are distributed in YAML format. They are compiled into CDB files via /usr/local/cpanel/bin/build_locale_databases.
  • Note: You can pass the build_locale_databases script the --help parameter for more information.
• The legacy system uses the English version of the language as its name, for example french. The name could also specify metadata such as encoding; for example, french-utf8.
• Cpanel::Locale uses ISO codes as the name; for example, fr or en_gb. No metadata can be included with this filename.
  • Locales are identified by the two-letter system established by ISO 639. These standards can be found here.
  • Region-specific locales are also identified by the two-letter standard established by ISO 639 followed by an underscore (_) and the two-letter standard established by ISO 3166.
• Language-only tags (such as es) have their lexicons merged into all region-specific tags of the same language (such as es_mx), in order to fill in any keys missing in a region-specific tag's database.
• In the new system, en is the default base language. en_us is an alias to en. This means that it cannot be created separately, as you could do with en_gb.
• The new character set will almost always be utf-8. You can find more information about this here.
• Legacy files and functionality are transparently handled via the Cpanel::Locale module.

Files Involved

The following portion of this document assumes that you are using the English language and the x3 theme.

The Legacy System

Root-specific files:

• /usr/local/cpanel/lang/english — The base file
• /usr/local/cpanel/lang/english.local — The local file

Theme-specific files:

• /usr/local/cpanel/base/frontend/x3/lang/english — The base file
• /usr/local/cpanel/base/frontend/x3/lang/english.local — The local file

The Locale System

Root-specific files:

• /usr/local/cpanel/locale/en.yaml — The base file
• /var/cpanel/locale.local/en.yaml — The local file

Theme-specific files:

• /usr/local/cpanel/base/frontend/x3/locale/en.yaml — The base file
• /usr/local/cpanel/base/frontend/x3/locale/en.yaml.local — The local file

Note: If you want to add or modify the value of a key, you should always modify the local file. Otherwise, your changes will eventually disappear. Any editing user interfaces in WHM and cPanel will edit the local files.