You can find our user documentation at

Check out our new API beta site!

Child pages
  • Tutorial - Localize Text in cPanel Plugins
Skip to end of metadata
Go to start of metadata


This tutorial creates and installs a fully-localized cPanel plugin. Localization allows users from many places to use your software.


  • This tutorial is for servers that run cPanel & WHM version 11.44 or later.
  • 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, cPanel, L.L.C. provides separate locales for Spanish and Latin American Spanish.

Localize plugin text

Use the locale.maketext system to localize your plugin's text.

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.


  • 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.

For more information and usage examples in several supported languages, read our Guide to Locales - Basic Usage documentation.

Use the LANG system to localize your plugin's install.json file.

Create the necessary install.json file for your plugin. The cPanel interface uses this file to add icons and groups to cPanel's dynamicui.conf file system automatically.

  • When you create this file for a localized plugin, you must localize the name value for each group and item in the file. This allows cPanel & WHM to correctly localize the name that displays with the icon in cPanel's Home interface.
  • The dynamicui.conf system's localization differs from the localization methods for other cPanel & WHM interfaces. For this reason, you cannot use the locale.maketext system to localize text in the install.json file.

To localize a name value, use the $LANG{} method. For example, the following install.json file localizes the display names from our Add a Link to the cPanel Interface tutorial:

      "name" : "Support",
      "order" : 11,
      "type" : "group",
      "id" : "custom_support_group"
      "icon" : "supportcontact.png",
      "group_id" : "custom_support_group",
      "order" : 10000,
      "name" : "$LANG{'Contact Support'}",
      "type" : "link",
      "id" : "contact_support",
      "uri" : ""
      "icon" : "knowledgebase.png",
      "group_id" : "custom_support_group",
      "order" : 10002,
      "name" : "$LANG{'Support Knowledge Base'}",
      "type" : "link",
      "id" : "support_kb",
      "uri" : ""

Create or update the desired locale files with your custom translations.

Copy or update, modify, and then import a customized version of the locale for each language that you wish to provide for your plugin.

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 (WHM >> Home >> Locale >> Locale XML Download) to export a copy of the XLIFF file.
  3. Translators use WHM's Locale XML Upload interface (WHM >> Home >> Locale >> Locale XML Upload) to import the XLIFF file.
  4. Translators update the locale lexicon(s) in WHM's Edit a Locale interface (WHM >> Home >> Locale >> Edit a Locale).
  5. Translators use WHM's Locale XML Download  interface (WHM >> Home >> Locale >> Locale XML Download) to export a copy of the XLIFF file.
  6. 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.


cPanel & WHM does not automatically translate text. You must provide updated locales with translated text for each string of text in your plugin's code and its install.json file.

Import your custom locale.

To import customized locales, you can use the /scripts/locale_import script. You can install the custom locale manually with this script, or include the use of this script in your plugin's installation scripts.

For example, the following command imports an updated de_ch locale:

/scripts/locale_import --locale=de_ch


Rebuild the server's locale databases.

To rebuild a server's locale databases, run the /usr/local/cpanel/bin/build_locale_databases script.

  • This script recompiles all of your server's locales. 
  • You can either run this script manually, or include the use of this script in your plugin's installation scripts.

Check the your plugin's localization.

Log in to cPanel on a test account and navigate to your plugin. Check the plugin in all of the customized languages that you included, to ensure that the localized text displays properly.