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:
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:
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>
…
- - -
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:
Code:
/var/cpanel/locale/$locale.gdbm (theme-independent)
/var/cpanel/locale/themes/x/$locale.gdbm
/var/cpanel/locale/themes/x2/$locale.gdbm
/var/cpanel/locale/themes/x3/$locale.gdbm
/var/cpanel/locale/themes/xmail/$locale.gdbm
/var/cpanel/locale/themes/x3mail/$locale.gdbmWhen 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:
Code:
/var/cpanel/locale.local/$locale.yaml (theme-independent)
/usr/local/cpanel/base/frontend/x/locale/$locale.yaml.local
/usr/local/cpanel/base/frontend/x2/locale/$locale.yaml.local
/usr/local/cpanel/base/frontend/x3/locale/$locale.yaml.local
/usr/local/cpanel/base/frontend/xmail/locale/$locale.yaml.local
/usr/local/cpanel/base/frontend/x3mail/locale/$locale.yaml.localThere 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>
…