Translating Invoices and Emails with Subscription Billing

by | Apr 15, 2022 | Billing Systems | 0 comments

Kill Bill is a open-source subscription billing and payments platform. Fully extensible, you can build your business logic on top of it for a customized billing and payments solution.


When it comes to international subscription billing, customers prefer to receive communications in their native language. Kill Bill supports translating invoices and emails into multiple languages. 

The number of languages Kill Bill can support is virtually unlimited. Adding a new, supported language involves adding a few files to the system. 

Here’s a basic graphic that shows how Kill Bill translates emails and invoices:

diagram showing Kill Bill email and invoice translation

Translating emails (or invoices) in Kill Bill

Sending emails to customers does require the email notification plugin (here’s a sample). The language support for invoices does not require a plugin. 

Let’s look at each of these elements in the following sections. 

Customer Account: Set the Default Language 

Each customer account in Kill Bill has a value assigned to the Locale field. One of this field’s uses is to tell the billing system the language to use when communicating with the account:

Kaui screen showing Locale

Kaui screen showing Locale field options (ISO location codes)

Before translating an invoice or email, Kill Bill checks the customer account’s Locale. The billing system then generates the document using the appropriate language template and resource file(s).  

Email and Invoice Templates

A template file is the basis for a generated email or invoice. A template includes static text, variables, and markup syntax. 

Let’s say your organization has the following emails related to subscription billing: 

  • New subscriber welcome
  • Invoice generated 
  • Invoice due
  • Thank you for paying invoice

For each email – plus the invoice – you’ll need a template in every language that you support. Within a template file, you use a combination of static text, variables, markup syntax for formatting, and Mustache syntax.

Here’s a line from the Kill Bill Upcoming Invoice email template: 

You have a new invoice from {{text.merchantName}}, due on {{invoice.targetDate}}.

If you also have French customers, you would create a French Upcoming Invoice email template. Here’s the same line in the French template: 

Vous avez une nouvelle facture de {{text.merchantName}}, due le {{invoice.targetDate}}.

The values surrounded by {{}} are tags used by Mustache, a template engine for creating dynamic content. Here’s another snippet of an email template from the Upcoming Invoice template:

Hello {{name}}! You have a new invoice from {{text.merchantName}}, due on {{invoice.targetDate}}.

{{#invoice.invoiceItems}}

{{startDate}} {{planName}} : {{formattedAmount}}

{{/invoice.invoiceItems}}

{{text.invoiceAmountTotal}}: {{invoice.formattedBalance}}

Mustache uses the template along with resource files to generate a translated email (or invoice). 

Resource Files

A resource file is a list of key-value pairs; each pair is a variable plus a translated string: 

upcomingInvoiceSubject=You Have a New Invoice

When generating an email or invoice, Kill Bill (with the help of Mustache) replaces the variables used in the template with the translated strings. 

Here are several more key value pairs from the default (English) resource file:

invoiceNumber=Invoice #

paymentDate=Payment Date

invoiceAmountPaid=Paid

invoiceAmountTotal=Total

billedTo=Billed To:

Kill Bill has two types of resource files: 

Catalog resource file: Translates catalog strings into a specific language. Typically, these catalog strings are referenced when generating the invoice. You’ll have a catalog resource file for each language you support (Examples:  CatalogTranslation_fr_FR.properties, CatalogTranslation_en_US.properties) .

Text resource file: Translates text strings specific to an email or invoice. Text resource files can also contain non-translatable key-values, such as merchantContactPhone or paymentDate. For each language you support, you will have a text resource file (Examples: Translation_fr_FR.properties, Translation_en_US.properties).

Use Kaui to Manage Translation Files

By the way, you can use Kaui (Kill Bill’s admin user interface) to upload and manage some of these files. Go to the tenant configuration page and look for these tabs: 

Kaui tenant configuration tabs

Kaui template and translation tabs

Adding New Supported Languages Is Easy

As you can see, Kill Bill’s method for translating invoices and emails is straightforward. If you ever need to add a newly supported language, you just create new templates and resource files and upload them to Kill Bill. 

We hope you enjoyed the dive into this aspect of multi-language support for subscription billing. For a high-level overview of Kill Bill’s internationalization capabilities, check out this blog post: International Recurring Billing & Payments: What You Need to Know.

Other resources: