Enable multilingual support in HTML billing document templates

Enable multilingual billing document templates in the tenant

To enable the localization of billing documents in PDF in your tenant, perform the following steps through the Zuora UI:

1. Click your username at the top right and navigate to Billing > Manage Billing Document Configuration.
2. Click the Translation Profile tab.
3. In the Translation Profile area, click edit.
4. From the Enable PDF Translation list, select Yes.
5. Click save to save the configurations.

Specify valid merge fields in the translation profile

Only valid merge fields or SPECIAL.PPOC in the translation profile can be translated. You can refer to the Object Scheme explorer available on the Edit HTML Template page to specify merge fields that will be translated flexibly. Click the  icon at the bottom-left corner of the Edit page to open the explorer.

You need to follow the following rules when specifying the merge field values:

• A valid translatable merge field must be in the object.field format. In the explorer, some items are not displayed in the object names. You need to refer to the annotations to identify the object name. In the below example, because the object name of BillTo is Contact, a valid merge field should start with Contact, such as Contact.AccountId.

 

• The field type must be String.

• You cannot specify objects or fields that don't exist in the Object Scheme explorer.

• The object position must be a single object. You can refer to the data type annotations in the explorer to identify the correct object name. For example, if you want to translate the ChargeName field on the Invoice Item object, use InvoiceItem.ChargeName in the translation profile.

Note that in the explorer, the display name is InvoiceItems. But the annotation of this item is List of InvoiceItem. You need to use the singular object name InvoiceItem. The below screenshot demonstrates the position of the correct values:

Create and upload a translation profile

Before exporting your translation profile, you must first upload it in CSV format. The system does not have any default files or values. You can refer the sample files below for reference:

Sample 1

MergeFieldName,OriginalValue,ja-JP
Account.Name,Butterfly,蝶
Contact.Country,United States,アメリカ合衆国
Contact.State,California,カリフォルニア

Sample 2

MergeFieldName,OriginalValue,zh-CN,ja-JP
Account.Name,Butterfly,蝴蝶,蝶
SoldToContact.Country,United States,美利坚合众国,アメリカ合衆国
SoldToContact.State,California,加利福尼亚,カリフォルニア

To create and upload a translation profile, complete the following steps:

1. Click your username at the top right and navigate to Billing > Manage Billing Document Configuration.
2. Click the Translation Profile tab.
3. In the Translation Profile Detail section, choose HTML as the template format.
4. Click Export. A translation file is downloaded with only the MergeFieldName and OriginalValue columns. You can create and edit a merge field in HTML format manually by specifying an object and field name in the translation profile. 
   • MergeFieldName: The merge field name as it appears in the billing document template.
   • OriginalValue: The value given in the language of your tenant. The maximum allowed length is 500 characters.

5. Add a language you want to translate to in each of the remaining columns. Type the language code in the column heading, for example, de-DE. The language codes are case-sensitive. You need to type exactly as shown in the Supported languages section below. The maximum allowed length is 500 characters.

6. Save the translation file. If you use Microsoft Excel to edit the translation file, save the file in the Windows Comma Separated (.csv) format. 

   • Do not save in the MS-DOS Comma Separated (.csv) format.
   • You must save the translation file in the UTF-8 Format.

7. In the Import Translation Profile section, click Choose File, select the translation CSV file, and click import.

8. Review the import summary and click OK.

9. Click and select a language in the translation file to review the translation.

Now, you can manage billing document template files and generate billing document PDF files as described in Merge Field mapping for billing documents.

With the example translation profile below, the two merge fields will render translated values because these are the only two provided in the translation profile. All other merge fields will be displayed in the default language that is used in the product catalog.

MergeFieldName	OriginalValue	fr-FR	de-DE
Product.Name	Best Product Ever	Meilleur Produit Jamais	Beste Product aller Zeiten
RatePlan. Name	Best Product Ever - Gold Edition	Meilleur Produit Jamais - Edition d'Or	Beste Produkt aller Zeiten - Gold Edition

Translate strings for Proration, Prepayment, Overage, and Credit

In addition to the supported merge fields, you can translate the following strings using the SPECIAL.PPOC merge field:

• — Proration
• — Prepayment
• — Overage
• Credit
• — Proration Credit
• — Prepayment Credit

The above SPECIAL.PPOC strings are suffixes appended to invoice or memo item names for a proration, a prepayment, an overage, or a credit. For example, the prorated invoice item name would be "XXX -- Proration" for the invoice or memo item named, "XXX". Invoice or memo items with the SPECIAL.PPOC suffixes are translated separately from the regular invoice or memo item names.

The following is an example translation profile for the special merge fields.

MergeFieldName	OriginalValue	ja-JP
SPECIAL.PPOC	-- Overage	過剰
SPECIAL.PPOC	-- Prepayment	元払い
SPECIAL.PPOC	-- Proration	比例配分
SPECIAL.PPOC	Credit	クレジット

Supported languages

The language country codes are comprised of two arguments separated by a dash, for example, fr-CA is French Canadian:

• The first argument is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639. 
• The second argument to both constructors is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. 

Billing document template merge fields can be translated into the following languages: 

Limitations

The localization of billing documents in PDF has the following limitations:

• A Zuora tenant can contain 5,000 translations for billing document PDF files. If you upload multiple translation profiles, the sum of all the translated merge field values should be less than 5,000 rows. 
• Translations cannot be removed.
• Translation messages cannot be updated directly through the Zuora UI. To update a translation, you have to upload a new translation file with the updated message.

Known issues

Do not use Excel on Mac systems to create a translation profile file for multi-byte languages. The characters may not be saved correctly.

We recommend Google Spreadsheet or a plain text editor, such as Sublime, to create a translation profile on Mac.