[Development Guides Home](/guides) >> [Quickstart Development Guide](/guides/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`](https://go.cpanel.net/CPANLocaleUtils) 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](https://docs.cpanel.net/whm/transfers/transfer-or-restore-a-cpanel-account/#restricted-restore).


For more information and usage examples in several supported languages, read our [Guide to Locales - Basic Usage](/guides/guide-to-locales/guide-to-locales-basic-usage) documentation.

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

Create the necessary [`install.json`](/guides/guide-to-cpanel-plugins/guide-to-cpanel-plugins-add-plugins) file for your plugin. The cPanel interface uses this file to add groups to [cPanel's `dynamicui.conf` file system](/guides/guide-to-cpanel-plugins/guide-to-cpanel-plugins-the-dynamicui-files) 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*](https://docs.cpanel.net/cpanel/the-cpanel-interface/the-cpanel-interface/) 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](/guides/quickstart-development-guide/tutorial-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*](https://docs.cpanel.net/whm/locales/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*](https://docs.cpanel.net/whm/locales/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*](https://docs.cpanel.net/whm/locales/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*](https://docs.cpanel.net/whm/locales/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](/guides/guide-to-locales/guide-to-locales-distribute-a-custom-locale) documentation.

Important:
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 `/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](/guides/guide-to-locales/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](/guides/guide-to-locales/guide-to-locales-troubleshooting) documentation.
* For help to test other cPanel plugin issues, read our [Guide to Testing Custom Code](/guides/guide-to-testing-custom-code) documentation.