Jan 26, 2011
Houston, TX
cPanel Access Level
Root Administrator
I have noticed various posts in the forums that describe problems that arise when trying to edit translations for a locale. The following overview may shed some light on these issues, particularly those involving uploaded XML files not working.

- - -

Modifying translations of the cPanel’s front-end interface can be accomplished in a few different ways. The following overview explains the basics and may help you figure out the most effective way to update translations to suit your needs.

The actual translation for a given element that is rendered to a cPanel user within his or her browser is ultimately determined by two files: the core database file and its corresponding local file (which may or may not exist). Basically, if a value for a particular translation exists in a local file, that value will be used. If there is no value present in the local file or the local file does not exist, the value found in the core file will be used. The following describes core and local files in more detail:

Core files
A core database file exists for each theme for a given locale. There is also a root (theme-independent) database file each locale. By design, values contained in core database files are never overwritten when making changes in WHM and they should not be edited directly. It is possible, however, to add new values to the core database via WHM’s “Edit a Locale” utility (more information below). Core translation databases can be found at the following paths:

/var/cpanel/locale/$locale.gdbm (theme-independent)
Local files
When a user edits a translation via WHM, the key and value for the given translation is copied into a local file. Any translations found within these local files will override their corresponding core translations. This means that the translations stored in the local files will be displayed in the front-end interface instead of the translations from the core database. Note that the local file for a given locale and theme will not exist until a user modifies at least one of its translations. Also note that is possible to create and/or edit local files directly via the command line. Local translation files can be found at the following paths:

/var/cpanel/locale.local/$locale.yaml (theme-independent)
Modifying a translation
There are essentially four ways to modify translations: Live editing, Bulk editing, uploading an XML file, and editing the local files directly.

Live Mode

WHM: Main >> Locales >> Edit a Locale
When Live Mode is selected, the Cpanel front-end interface is opened in a WYSIWYG-type mode where the user can edit each translation as it normally appears to an end user.

Bulk Mode
WHM: Main >> Locales >> Edit a Locale
This mode presents the user with a list of translations for to the selected theme. Displayed for each item in the list are its key, the English value for this key, and the currently selected locale’s value, the value of which can be modified by clicking the Edit button.

XML Upload
Main >> Locales >> Locale XML Upload
This is a form that the user can use to upload an XML file containing new and/or modified translations. The XML file will most likely be an altered version of a file acquired by downloading an XML file from the Locale XML Download utility. It is important to note that the uploaded XML file is handled in different ways depending on the circumstances. Note the following two scenarios:

A) The locale does not yet exist on the server
A new locale will be created. The name of this domain is determined by the XML file’s <item key="locale"> tag. Thus, custom locales can be created by cloning a current locale and changing this tag. This works for both official locales defined by CLDR and custom locales. Custom locales should conform to the i_customlocalename naming convention so as not to clash with the names of official locales.

B) The locale already exist on the server
Core and local files are affected differently when the user uploads a customized XML file to the server:
Core - updates to core translations within the XML file will be ignored*. This means that a user cannot simply change the values and expect them to be incorporated. On the other hand, new keys for core translations will be added to the core database.
Local - updates to local translations will overwrite values in the local translation files on the server. New keys will be added to the local translation files.

* An XML file obtained via the Locale XML Download utility will not contain the appropriate section for updating local translations unless local overrides for the corresponding locale existed on the server at the time of the download. Modifications to the core values within the XML file will be ignored. To get around this, ensure that at least one translation has been modified before downloading the XML file. This will force the local section to be present at the bottom of the XML file to which more values can be added as necessary.

Example of copying core translation to local section of XML file:

<item key="/usr/local/cpanel/base/frontend/x3/lang/iberian_spanish">
<item key="data">
<item key="gswnochange">No copie este tag</item>
<item key="gswtitle">Asistente para comenzar</item>
<item key="gswlangdesc">Para comenzar, por favor selecciona el idioma en el cual deseas utilizar tu interfaz.</item>

You should only copy the <item> tags containing phrases that you want to change to the local section:

<item key="/usr/local/cpanel/base/frontend/x3/locale/es_es.yaml.local">
<item key="data">
<item key="gswtitle">Chunche ayudante</item>
<item key="gswlangdesc">Varas, mae! Si quieres comenzar, selecciona el idioma en el cual deseas utilizar tu interfaz.</item>


Well-Known Member
Mar 22, 2008
It would be nice why translations suddenly disappear completely after editing a specific word. Honestly the translation system in cPanel is such a pane that I considered dropping cPanel because of this. I never saw any software that was so terrible and complicated to translated. It doesnt matter what you use, the WHM interface or the an offline editor I was able to find bugs and kill them in all possible way.

Suddenly all your translation can be wiped out without any reason. You can upload your backup xml file 100 times and the translation will not show up again. Sometimes even the WHM editor will break up and you are stuck without being able to use it anymore. The only solution I found is to translated again from scratch. Nice, 52,000 lines from scratch because the provided locale that come as default as translated by a monkey so bad are they.

At least let your customers translated the system hours, weeks or months with a security they can backup their work and it will not be vanished in another cPanel upgrade.

Why dont you start with more simple instructions like how to force the cache or what ever cPanel has to force to see new changes in the locale?

It seems you can translated for hours and everything is fine, until suddenly you change 1 single word, and upps, all your work is gone. Not only that work, but everything you made is not displaying anymore. Its so frustrating that is completely useless.


Well-Known Member
Mar 22, 2008
So how can you dump all the text from a core file to a locale file?

Your explanation says the locale file will actually contain phrases and keys already modified and yes, this is the case. So how does someone edit the XML offline if all the keys are missing from the download?

If you want to edit offline then all missing text should be there, there is no point downloaded a blank xml download. How can you dump a core file into a XML download for offline translation?