Development Guides Home >> Quickstart Development Guide

Tutorial - Localize Text in cPanel Plugins

Introduction

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

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.

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 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" : "https://support.example.com"
   },
   {
      "icon" : "knowledgebase.png",
      "group_id" : "custom_support_group",
      "order" : 10002,
      "name" : "$LANG{'Support Knowledge Base'}",
      "type" : "link",
      "id" : "support_kb",
      "uri" : "https://supportkb.example.com"
   }
]

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.

Import your custom locale

To import customized locales, you can use the /usr/local/cpanel/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:

/usr/local/cpanel/scripts/locale_import --locale=de_ch

• To view additional options for this script, run the /usr/local/cpanel/scripts/locale_import --help command.
• For more information, read our Guide to Locales - Distribute a Custom Locale documentation.

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.

• For help to troubleshoot localization issues, read our Guide to Locales - Troubleshooting documentation.
• For help to test other cPanel plugin issues, read our Guide to Testing Custom Code documentation.