Introduction
Use this document to troubleshoot common locale system issues.
Remember:
Never modify locale system data manually. Instead, use WHM's Locales interfaces (Home >> Locales) to create and update locales.
Corrupt or absent localized text
Note:
In this document, the term "hardcoded" refers to text that you did not properly mark for translation in the code.
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-8character encoding (for example, Sublime Text). -
Delete the
charsetkey in the file. - Save the file with the
utf-8character 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 file updated correctly, the output will include the string
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:12<metacharset="utf-8"><metahttp-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 nonprintable characters.
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.
Remember:
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 typos.
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.
Remember:
The locale system cannot translate phrases on demand. A translator must translate each phrase in the appropriate lexicons.
'Could not find key' errors
Problem:
You see an error that is similar to the following example:
|
1
2
3
|
/path/to/file.html :: Could not find key via 'X' locale: 'Hello World' Cpanel::Locale::X : /var/cpanel/locale/... |
Solution:
Ensure that the locale's lexicon and the base locale's lexicon are properly compiled.
For more information, run the following command as the root user:
/usr/local/cpanel/bin/build_locale_databases --help |
Explanation:
The locale system could not find the phrase in the locale's lexicon or in the base locale's lexicon because the CDB databases were improperly compiled.
'Could not find key' error with blank text
Problem:
You see an error that is similar to the following example:
|
1
2
3
|
/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, trigger an error in the locale system.
'Could not find key' error with blank text
Problem:
You see an error that is similar to the following example:
|
1
2
3
|
/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, trigger an error in the locale system.
'Can't use "..." as a method name in bracket group' error
Problem:
You see an error that is similar to the following example:
|
1
|
Can't use "output_asis" as a method name in bracket group, in: All of the server’s [output_asis,DNS] resolvers fail to respond. |
This indicates that the translation string uses bracket notation methods that are not allowed by cPanel & WHM's bracket notation whitelist settings.
Solution:
Check for typos in the bracket notation syntax.