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
  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. Chargebee supports two languages at the moment : French and German (Spanish, Portuguese and Italian are on the way!).

  4. 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 French and German.

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:

  • 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?

    As with the Optional folder, the emails folder contains translations of Chargebee's default email notification content. You should populate this folder with translations only if you plan to customize the existing emails. If you do, 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 new subscription  call that you send across via API.

  • Via the Customer Portal: A customer can always override any previous settings by choosing 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 checkout page.


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

Navigate to Settings > Field Configurations > Languages to 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.


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

Yes. You need to provide a separate language pack for each customer language that you would like to enable in Chargebee. This means that if you would like to communicate with your customer 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.