Skip to main content

Enable multilingual support in Word billing document templates

Zuora

Enable multilingual support in Word billing document templates

If you operate a global business with customers in multiple languages, you can dynamically generate PDF files for billing documents, including invoices, credit memos, and debit memos, in your customers' preferred languages using one template.

This article describes the process of setting up and generating PDF files for billing documents in multiple languages.

Zuora translates only text-based merge fields using the uploaded translation profile. It selects the language for translation using the locale in customer's communication profile. If the translation profile does not contain a column for the customer's communication profile locale, the original untranslated value for the merge field is used.

Date and numeric merge fields are formatted based on the locale in the customer's communication profile.

To generate PDF files for billing documents in multiple languages:

  1. Enable the localization of billing documents in PDF in your tenant.
  2. Create and upload a translation profile file for the languages you want to translate your billing document PDF files into.
  3. Edit and generate invoice PDF files or memo PDF files. You do not need to make any additional change to billing document templates for translation.

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.

Create and upload a translation profile

A merge field value can be translated if all of the following are true about the merge field:

  • A supported merge field name or SPECIAL.PPOC is used.
  • The merge field is not marked as untranslatable.
  • The field type is string.

For the names, types, and translatability of merge fields, see Merge Fields for Invoices, Merge Fields for Credit Memos, or Merge Fields for Debit Memos.

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 Word as the template format.
  4. Click Export. A sample translation file is downloaded. The translation file contains only the MergeFieldName and OriginalValue columns.
    • 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 Customize Billing Document Templates Using Word Mail Merge.

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
Subscription.Product.
Name
Best Product Ever Meilleur Produit Jamais Beste Product aller Zeiten
Subscription.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.

SPECIAL.PPOC is not a true mail merge field and cannot be used in billing document templates.

Do not use any of the above SPECIAL.PPOC strings at the end of your charge names. Otherwise, the charge name might be incorrectly translated.

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: 

English languages

Language Code
English (United Kingdom) en-GB
English (United States) en-US

German languages

Language Code
German (Austria) de-AT
German (Germany) de-DE
German (Luxembourg) de-LU
German (Switzerland) de-CH

Chinese languages

Language Code
Chinese (PRC) zh-CN
Chinese (Singapore) zh-SG
Chinese (Taiwan) zh-TW

French languages

Language Code
French (Belgium) fr-BE
French (Canada) fr-CA
French (France) fr-FR
French (Luxembourg) fr-LU
French (Switzerland) fr-CH

Spanish languages

Language Code
Spanish (Argentina) es-AR
Spanish (Bolivia) es-BO
Spanish (Chile) es-CL
Spanish (Columbia) es-CO
Spanish (Costa Rica) es-CR
Spanish (Dominican Republic) es-DO
Spanish (Ecuador) es-EC
Spanish (El Salvador) es-SV
Spanish (Guatemala) es-GT
Spanish (Honduras) es-HN
Spanish (Mexico) es-MX
Spanish (Nicaragua) es-NI
Spanish (Panama) es-PA
Spanish (Paraguay) es-PY
Spanish (Peru) es-PE
Spanish (Puerto Rico) es-PR
Spanish (Spain) es-ES
Spanish (United States) es-US
Spanish (Uruguay) es-UY
Spanish (Venezuela) es-VE

Arabic languages

Language Code
Arabic (Algeria) ar-DZ
Arabic (Bahrain) ar-BH
Arabic (Egypt) ar-EG
Arabic (Iraq) ar-IQ
Arabic (Jordan) ar-JO
Arabic (Kuwait) ar-KW
Arabic (Lebanon) ar-LB
Arabic (Libya) ar-LY
Arabic (Morocco) ar-MA
Arabic (Oman) ar-OM
Arabic (Qatar) ar-QA
Arabic (Saudi Arabia) ar-SA
Arabic (Sudan) ar-SD
Arabic (Syria) ar-SY
Arabic (Tunisia) ar-TN
Arabic (U.A.E.) ar-AE
Arabic (Yemen) ar-YE

Other languages

Language Code
Bulgarian (Bulgaria) bg-BG
Czech (Czech Republic) cs-CZ
Danish (Denmark) da-DK
Dutch (Belgium) nl-BE
Dutch (Netherlands) nl-NL
Estonian (Estonia) et-EE
Finnish (Finland) fi-FI
Greek (Cyprus) el-CY
Greek (Greece) el-GR
Hungarian (Hungary) hu-HU
Italian (Italy) it-IT
Italian (Switzerland) it-CH
Japanese (Japan) ja-JP
Latvian (Latvia) lv-LV
Norwegian (Norway) no-NO
Polish (Poland) pl-PL
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Romanian (Romania) ro-RO
Russian (Russia) ru-RU
Slovak (Slovakia) sk-SK
Slovenian (Slovenia) sl-SI
Swedish (Sweden) sv-SE
Thai (Thailand) th-TH
Turkish (Turkey) tr-TR

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.