Development Guides Home >> Guide to Locales

Guide to Locales - Troubleshooting

Introduction

Use this document to troubleshoot common locale system issues.

Warning:

Never modify locale system data manually. Instead, use the interfaces in WHM's Locales section (WHM >> Home >> Locales) to create and update locales.

In this document, the term "hardcoded" refers to text that you did not properly mark for translation in the code.

Corrupt or absent localized text

Problem

Characters appear corrupt in the browser (for example, "I � Unicode" instead of 'I ♥ Unicode').
Characters or entire phrases do not display at all.

Solution

In most cases, this problem occurs because the file uses the wrong character set. To change a file's character set, perform the following steps:

Locate the file on the server that contains the string.
Open this file in a text editor that allows you to save files in the utf-8 character encoding (for example, Sublime Text ).
Delete the charset key in the file.
Save the file with the utf-8 character encoding. If the file is not irreparably corrupt, the program that you used will convert it.
Recompile the CDB file.
If the file updated correctly, the output will include the string File updated '...cdb' .
If the file did not update correctly, the output will include the string ' CDB file '...cdb' is already current' .

If the text remains corrupt after you update the file's character set, perform the following steps:

View the page source in your preferred browser. The <head> section of the HTML source should include one of the following tags:
```
<meta charset="utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
```
If neither of these tags exist, add one of them to the <head> section of your HTML or Template Toolkit file.

If the text does not display at all, make certain that the phrase is properly wrapped in a maketext() call. If it is, run the /usr/local/cpanel/bin/build_locale_databases script to recompile your server's locales.

Explanation

If characters appear corrupt in the browser, then the character set in the headers does not match the data. Unless the data is corrupt, this can only happen if the data is encoded in the wrong character set. An incorrect character set can also cause characters to display as whitespace characters or non-printable characters.

For more information, read our Why UTF-8? documentation.

If the characters do not appear at all, then you may have hardcoded the text, or you may need to rebuild your locale's cdb file.

Corrupt locale names, dates, or times

Problem

Locale names, dates, or times appear corrupt or do not display with the correct formatting.

Solution

Ensure that your font supports Unicode characters.
File a bug report with the Unicode Common Locale Data Repository (CLDR) .

Explanation

The locale system retrieves locale names directly from the CLDR. For this reason, problems in locale names are rare, and originate from the CLDR rather than from cPanel & WHM.

Important:

Lowercase names or dates, parenthetical English names that display to the left of text, and unfamiliar characters are often correct in other languages, though they may appear incorrect to native English speakers.

Some phrases are not translated

Problem

Some phrases are not translated into the correct language, but others display correctly.

Solution

Ensure that the untranslated phrase is within the maketext() method in the source code.
Ensure that the untranslated phrase exists in both the default English lexicon and in the selected locale's lexicon.
Ensure that the untranslated phrase is not misspelled and does not contain any typographical errors.
If you used the the /var/cpanel/debughooks file to enable debug mode, run the following commands to disable debug mode and restart the cpsrvd daemon:
```
echo -n > /var/cpanel/debughooks
/scripts/restartsrv_cpsrvd
```

Explanation

If the locale system cannot locate a translated version of a phrase in the selected locale's lexicon, it will display the phrase in English. The locale system cannot translate phrases on demand. A translator must translate each phrase in the appropriate lexicons.
If you enabled debug mode for cPanel & WHM's Standardized Hooks system, your locale may temporarily revert to the English defaults for JavaScript elements.

'Could not find key' errors

Problem

You see an error that resembles the following example:

/path/to/file.html :: Could not find key via 'X' locale:
 ''
 Cpanel::Locale::X : /var/cpanel/locale/...

Solution

Check your custom code for syntax errors or blank phrases.

For example, the following code would return this error:

$locale->maketext(' ');

Explanation

Blank phrases, or syntax errors that return a blank phrase, cause an error in the locale system.

'Can't use "..." as a method name in bracket group' error

Problem

You see an error that resembles the following example:

Can't use "..." as a method name in bracket group, in: ...

This error indicates that the localized string uses bracket notation methods that cPanel & WHM's locale system's whitelist settings do not allow.

Solution

Check for typographical errors in the bracket notation itself. Often, developers see this error because the method name is misspelled.
If no error exists, check whether cPanel & WHM's bracket notation method whitelist includes the bracket notation method.
- For a complete list of whitelisted bracket notation methods, read our Guide to Locales - The Bracket Notation Whitelist documentation.
- If cPanel & WHM's bracket notation method whitelist does not include the desired method, you must add it.

Explanation

To prevent the execution of arbitrary or malicious code when the locale system processes a localized string, cPanel & WHM only allows specific bracket notation methods by default. The locale system also automatically blacklists methods that begin with the underscore character (_) and methods that include Perl namespace separator characters. Therefore, bracket notation methods that do not appear in this whitelist will cause an error.