Troubleshooting PDF Values With Non-English Language

Overview

When deploying Sugar, the PDF engine only has the capability to display specific characters. This article covers how to add additional language support for PDF rendering.

Symptoms

When logged in using some non-Western languages, most notably Japanese or Chinese, PDF files generated by the application may contain a string of question marks (e.g. "????") in place of certain words. There is an existing enhancement request to look into other PDF engines that offer broader multilingual support. At this time, some fonts for the TCPDF engine utilized by Sugar are not packaged with the product due to licensing issues. Depending on how your instance of Sugar is hosted, you will follow the appropriate steps to add support for your language.

Resolution

On-Site Instances

1. Download a current package of TCPDF fonts from: http://sourceforge.net/projects/tcpdf/files/
2. Extract the desired files from the fonts directory in that package. For example, stsongstdlight.php is for simplified Chinese.
3. Place the font files in the ./custom/vendor/tcpdf/fonts/ directory of your Sugar installation. Once installed, you should ensure that they have proper permissions for the web server to read and access the files.
4. Log into Sugar as an administrator, navigate to Admin > Repair, and perform a "Quick Repair and Rebuild". This action includes a process that rebuilds the ./cache/Sugarpdf/cachedFontList.php file which references the available fonts for Sugar.
5. Navigate to Admin > User Management and select the user who will use the new font.
6. Once in the user's profile, click the Edit button, select the Advanced tab, and scroll down to the PDF Settings section.
   
   Note: The Users module utilizes the Sidecar user interface in Sugar versions 13.3 and higher.
7. Update the "Font for Header and Body" and "Font for Footer" fields with the newly installed font value.
   Note: The user can also make the change in their user account by navigating to their user profile and following steps 6-7.
8. Click "Save" to preserve the changes.

SugarCloud Instances

1. You will need to create a module loadable package that copies your fonts to the ./custom/vendor/tcpdf/fonts/ directory.
2. File a Support case with your module loadable package attached and reference this knowledge base article to have the font pack installed on your cloud-hosted instance.
3. Once the package is installed, navigate to Admin > User Management and select the user who will use the new font.
4. Once in the user's profile, click the Edit button, select the Advanced tab, and scroll down to the PDF Settings section.
   
   Note: The Users module utilizes the Sidecar user interface in Sugar versions 13.3 and higher.
5. Update the "Font for Header and Body" and "Font for Footer" fields with the newly installed font value.
   Note: The user can also make the change in their account by navigating to their user profile and following steps 4-5.
6. Click "Save" to preserve the changes.