Child pages
  • Guide to Locales - Troubleshooting
Skip to end of metadata
Go to start of metadata

 

Introduction

Use this document to troubleshoot common locale system issues.

Remember:

Never modify locale system data manually. Instead, use the interfaces in WHM's Locales section (WHM >> 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:

  1. Locate the file on the server that contains the string.
  2. Open this file in a text editor that allows you to save files in the utf-8 character encoding (for example, Sublime Text).
  3. Delete the charset key in the file.

  4. Save the file with the utf-8 character encoding. If the file is not irreparably corrupt, the program that you used will convert it.
  5. 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:

  1. 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">
  2. 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:

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 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.

    Remember:

    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:
    '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 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.

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. Therefore, bracket notation methods that do not appear in this whitelist will cause an error.

Important:

The locale system automatically blacklists methods that begin with the underscore character (_) and methods that include Perl namespace separator characters. 

The WHM Home interface displays incorrect locale


Problem: 

Users encounter an incorrect locale in WHM's Home interface after they upgrade to cPanel & WHM version 66.

Solution: 

 Run the following command:

mv /var/cpanel/caches/_generated_command_files{,.backup}

Explanation:

This command clears the locale caches, which corrects the issue.