[Development Guides Home](/guides)

# Guide to Locales

## Introduction

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

[Localization](https://en.wikipedia.org/wiki/Language_localisation) 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`](https://go.cpanel.net/CPANLocaleUtils) documentation.

div
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](https://docs.cpanel.net/whm/transfers/account-restore/).


## 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)](http://cldr.unicode.org/) as locale names (for example, `fr` for French or `en_gb` for British English).

* Locale names for base languages may use [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1)'s two-letter system, while region-specific locale names include this two-letter code, an underscore (`_`), and the [ISO-3166](http://en.wikipedia.org/wiki/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*](https://docs.cpanel.net/whm/locales/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](/guides/guide-to-locales/guide-to-locales-basic-usage) documentation.
* You can distribute locales. For more information, read our [Distribute a Custom Locale](/guides/guide-to-locales/guide-to-locales-distribute-a-custom-locale) documentation.
* You can delete custom locales. For more information, read our [Delete a Locale](https://docs.cpanel.net/whm/locales/delete-a-locale/) documentation.


div
Warning:

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