Getting Started

Building Blocks

Subscription Features




Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages

Attach Additional Data


Open Source Resources

Other Features

API Integration

Third Party Integrations

Configure Multiple Languages 

If you are selling to customers around the world, and would like to communicate with them in their native languages, the Localization feature is for you.

What does Chargebee localize? 

With the the Localization feature, you can localize the following elements of your customer communication:

  • Invoices and Credit notes
  • Email Notifications
  • Hosted Pages and Customer Portal
  1. Using the localization feature will not affect your in-app experience.

  2. While Chargebee can translate words and terms that are common to all hosted pages, emails, invoices and credit notes, it cannot translate words that are specific to your product catalog (like the names of your plans, for example). Chargebee uses a language pack to translate these terms. More on language packs here.

  3. Checkout the pricing page   to figure out which one of our localization options is for you.

Understanding the Localization Feature 

Default Customer Language

Your default customer language is the language that Chargebee uses to communicate with your customers if you haven't configured any other language for your site. The default customer language cannot be updated or changed to another language after your initial setup.


Chargebee will revert to the default customer language if it cannot find a translation of a word in your language pack.

Other Customer languages

Apart of from the default customer language, Chargebee can be equipped to send out customer communication in other languages. Here is a list of languages that Chargebee supports:

  • French
  • German
  • Spanish
  • Portuguese
  • Italian

Contact  to activate a language that is not listed here.

Language packs

A language pack equips Chargebee with all that it needs to translate your hosted pages, invoices, email notifications and credit notes to another language.

You need to compile a language pack for each language that you would like to use with the localization feature.

Each language pack contains three folders: a mandatory folder, an optional folder and an emails folder.

  • Mandatory Folder

    What does the Mandatory folder contain?

    The Mandatory folder contains CSV files associated with each of the products in your product catalog (including your plan, add-ons and coupons). Each CSV files contains keys associated with words or terms that are specific to your product catalog. Translating these terms is essential - Chargebee cannot translate terms that you have complete control over by itself.

    What does the Mandatory folder translate?

    The Mandatory folder is used to translate product-specific terms (like your plan, addon and coupon names, invoice notes, tax notes) in your emails, hosted pages, invoices and credit notes. Here is a sample invoice translated to german with product-specific terms highlighted in orange:


If a product is added or updated, remember to capture the changes in the CSV. You can test the changes in your TEST site. More info on testing the localization feature here.

  • Optional Folder

    What does the Optional folder contain?

    The Optional folder contains a CSV file associated with the text configurations (including field labels, help texts, info and alerts) in your hosted pages - the non-product specific terms that appear on the Chargebee's hosted checkout pages, update payment method pages and customer portal.

    What does the Optional folder translate?

    Chargebee translates its default text configurations. If you would like to use your own text configurations, you can enter the translations here. Chargebee will refer to this folder when translating your hosted pages.

  • Emails Folder

    What does the Emails folder contain?

    The Emails folder contains subfolders associated with each customer email notification in the web interface. Each subfolder contains a translation of Chargebee's default email notifications in TXT and HTML formats.

    What does the Emails folder translate?

    The emails folder translates Chargebee's default customer email notification content.

    You should populate this folder with translations only if you plan to make any changes to Chargebee's default customer email notifications. If you decide to modify Chargebee's default emails, remember to upload HTML and TXT versions of the new emails you would like to send out.

See also

Check out the email notifications page for more info on Chargebee's customer email notifications

Incomplete Language Packs

  • If a product specific word/term has been left untranslated in your Mandatory folder (for example, your French language pack does not have the translated name of one of your Plans), Chargebee will display that field in the default language.

  • If a term or phrase has been left untranslated in your Optional folder or your Emails folder (for example, your German language pack does not have the translation of the Customer Created email), Chargebee will send out one of it's default translations for the same.


Some countries represent currency differently than usual (France uses a comma rather than a period when representing numbers, for example: 9,99 rather than 9.99). Chargebee will automatically follow appropriate conventions, taking cues from the language you have set for the customer. If a source for accurate formatting is not available, then Chargebee will utilise the base currency format for displaying the details (in this case: 9.99).

Configuring Customer Languages in Chargebee 

These steps will walk you through configuring the Localization feature in your Chargebee site.

Step 1: Set/Update a customer's locale

The customer locale object in Chargebee defines two things: Where your customer is located and what language is endemic to his location. An example of a customer locale is: French [Canada].

If you are using the Hosted Pages

If you are using the hosted pages, a customer's locale is captured in three ways, in increasing order of priority:

  • Via a customer's browser setting: Chargebee is equipped to automatically set a customer's locale by capturing her browser's locale setting. This essentially means that Chargebee will monitor your customer's browser settings so that her hosted checkout page appears in the same language as the rest of her webpages.

  • Via API: If you are using Chargebee's hosted pages with iFrame, Chargebee will not capture a customer's browser setting. Instead, it will set a customer's locale based on the accompanying checkout a new subscription  call that you send across via API.

  • Via the checkout page: A customer can override any previous setting by choosing a locale for herself. Check out step 6 for a guide on how to allow your customer to choose a locale on the hosted checkout page.

  • Via the Customer Portal: A customer can also set a locale for herself via the customer portal. She would need to navigate to the Edit Account Details page within the customer portal and select an appropriate locale from the menu there.

If you are not using the hosted pages

If you are not using the hosted pages or want update existing customer information, you can set customer locale:

  • Via the API: If you like to set a locale for your customer using the API, you can use the Create a Customer   call. You can use the Update a customer  call to set the locale for your existing customers.

  • Via the web interface: To communicate with an existing customer in a different language, go to the Edit Customer Details, navigate to Customer Details > Locale and select the locale that the customer belongs to.


Your existing customers' past invoices and credit notes will not be altered after language settings are updated. Only subsequent invoices and credit notes will be sent in the updated language.

Step 2: Download Chargebee's language pack

Setting up a language pack for Chargebee to use for translation is a crucial step to getting your localization feature off the ground. Navigate to Settings > Languages to download a language pack in your default customer language - this language pack will give you an idea of what terms specific to your product catalog you should translate for Chargebee to use in your hosted pages, emails, invoices and credit notes.

Step 3: Translate the terms in your language pack

Step three is the translation, which you could handle in-house or outsource to a translation agency. Make sure to translate each term in the language pack as Chargebee will revert to your default customer language or one of it's default translations if it is unable to find a translation for a particular term.

Step 4: Upload your complete language pack

When your translation is done, upload the completed language pack back to Chargebee. As with the download, you can do this on the Languages page (navigate to Settings > Languages).


You will need to upload a separate language pack for German and a separate language pack for French.

Step 5: Activate the language(s) you would like to use

With your language pack uploaded, you click the Activate option by language you would like to use. This informs Chargebee that it can go ahead and translate your customer communication if a locale is present for a customer.


You need a separate language pack for each language you would like to activate.

Step 6: Hosted Pages Options (Optional)

If you have more than one customer language (excluding your default customer language) configured in your site, you might want to let your customers choose their locales for themselves when they are on Chargebee's hosted pages.


This option is not available to users who are using Chargebee's hosted checkout page with iFrame.

Navigate to Settings > Field Configurations > Languages and click the Show option against Languagesto enable a pop-up menu on Chargebee's hosted pages that will allow your customer to view any of Chargebee's pages in a different language.


This dropdown menu cannot be enabled for the hosted pages via the API.

Testing the Localization Feature 

Once you have configured the locales of your customers, uploaded a language pack, and activated a language, you can test the localization feature in Chargebee. Testing your invoices, credit notes, hosted pages and email notifications are a good opportunity to check out what your customer communication looks like populated with the localized fields from your language pack.

Testing Invoices

To test your invoices with the localization feature, follow these steps:

  • Create a customer in Chargebee. Navigate to Subscriptions > Customers > Create a new customer to do so. Remember to enter the customer's locale when entering test customer information.

  • Put your test customer on a subscription to one of the plans in your product catalog. Choose the Create a new subscription option on the customer's details page. Remember to populate his profile with test payment information and set an appropriate start date.

  • With an active subscription, an invoice will be generated, visible in the Invoices section in the customer's details page.

  • You can generate multiple invoices to test every facet of your language pack including your coupon names, addon names and localized currency representation. Configure your test subscription (or make a new one) with coupons to review coupon names, addons to review addon names and taxes to review currency representation.

  • Click on the invoice to view it within the web interface or download the invoice PDF.

Testing Emails

You can view customer emails by navigating to Settings > Enable Email Notifications.

To view email notifications in another language, on the other hand, follow these steps to view a test email in a language that you have activated for your site:

  • Navigate to Settings > Enable Email Notifications and the set the email you would like to send to your customer to ‘ON'.

  • Navigate to your test customer's details page and enter an email ID for the customer (if you set your own email ID here, the email will come to you).

  • Execute the event that triggers the email dispatch. For example, if you have set the Invoice Receipt email to ON, generate an invoice for the customers and an email will automatically be dispatched to the email address on record.

Testing the Hosted Pages

To test your hosted pages with the localization feature, follow these steps:

  • As the language of the hosted pages is set by browser locale, you would need to update your browser settings - choosing the language you would like to view the hosted pages in to be your primary language.

Browser locale settings (which sets the locale for a customer) can be overridden via the create a customer   API call or the checkout a new subscription   API call. You can test this aspect of the feature as well. Specify a customer's locale via API and Chargebee will ignore the customer's browser locale settings.


  • Do I need separate language packs for each language that I want to activate?

You do not need a language pack to send out customer communication in your default language. However, You need to provide a separate language pack for each of the other customer languages that you would like to enable in Chargebee.

To illustrate, if you would like to communicate with your customer in French and German, with French being your default language - you would have to upload a German language pack only. On the other hand, if your default language is English and you would like to communicate with some of your customers in French and German - you would have to upload a French language pack and a German language pack.

  • I forgot to set a customer's locale and an invoice has been generated. This invoice is in English. Is there any way in which the invoice can be converted to French?

No, your invoice cannot be converted to French. Once an Invoice is generated in a particular language, it cannot be altered in any way.

  • What will happen to the old invoices if I disable a language (say, French) through language settings?

The old invoices that were in French will stay that way. Once an invoice is generated, it cannot be altered.

  • I forgot to translate my plan names in my German language pack. What will the invoice look like for the customer whose locale is set as German?

The entire invoice will be in German. However the plan description in the invoice will be in English. Chargebee reverts to the default customer language when it cannot find a translation in the language pack.

  • I forgot to translate the text in my Welcome Email (in my German language pack). What will the email look like?

Chargebee will refer to the default translation available for all email notifications. In case you've forgotten to translate an email, Chargebee will it's default translation (of your Welcome Email in German) to your customer.

  • I need to stop sending emails, and invoices in another language. Do I need to reset the site locale for every customer?

No, you don't need to change the locale of customers individually. Navigate to the Settings > Languages page to deactivate a customer language.

  • Can I activate a customer language after I have deactivated it?

Yes, as long as you have a language pack, you can turn on a customer language.