The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Email Template Languages

Recurly offers support for merchants to send their customers emails in the language that they prefer.

Supported Languages & Locales

Recurly supports a number of locales to allow you to communicate with international customers. A locale is a combination of language and country specific formatting for dates, times and numbers. We support the following locales:

Language
API Value

Chinese (China)

zh-CN

Danish (Denmark)

da-DK

Dutch (Belgium)

nl-BE

Dutch (Netherlands)

nl-NL

English (Australia)

en-AU

English (Canada)

en-CA

English (United Kingdom)

en-GB

English (Ireland)

en-IE

English (New Zealand)

en-NZ

English (United States)

en-US

Finnish (Finland)

fi-FI

French (Canada)

fr-CA

French (France)

fr-FR

German (Switzerland)

de-CH

German (Germany)

de-DE

Hindi (India)

hi-IN

Italian (Italy)

it-IT

Japanese (Japan)

ja-JP

Portuguese (Brazil)

pt-BR

Portuguese (Portugal)

pt-PT

Romanian (Romania)

ro-RO

Russian (Russia)

ru-RU

Slovakian (Slovakia)

sk-SK

Spanish (Spain)

es-ES

Spanish (Mexico)

es-MX

Spanish (United States)

es-US

Turkish (Turkey)

tr-TR

The number of locales you can enable varies by your Recurly plan. In the Core plan, we allow you one language, and you can change your default language. We allow 5 languages in the Pro Plan and Unlimited in the Enterprise Plan.

Please see our pricing page or contact us for more information.

Throughout the rest of this documentation, we will use the word "Language" instead of "Locale" for simplicity's sake.

Enabling Languages for your Recurly site

In order to enable a new language for your site, navigate to Configuration > Email Templates > Configure Languages.

On this page you can select a new language to enable for your site.

Enabling a language allows you or your customers to specify it as their email language. Once the customer's language is set they will begin receiving all email communications using that language's templates.

In Hosted Payment Pages, Hosted Account Management Pages, and Recurly Admin UI only enabled languages will be visible in the Email Language drop down.

Trying to assign a disabled language to a customer using the API will result in a validation error.

Setting A Default Language

Recurly offers the ability to set a default language for a site. By default, this is English (United States). This language will be used for all customers that have not selected a language, or have a disabled language selected.

If your Recurly plan allows multiple languages you can set any enabled language as the default. If your plan only allows a single language switching the default language will enable the new choice and disable the old one.

Disabling A Language

If you set up an email language and would later like to disable it, you can also do that on the Configure Languages page. All customers with the disabled language selected on their account will immediately begin receiving emails in the site's default language.

Customer Language Preference

Each customer has a email language field that determines which email templates they will receive. This can be set through a number of ways:

  • The API (account creation and edit)
  • Hosted Payment Pages
  • Hosted Account Management Pages
  • The Recurly UI (can be added or edited on each customer account)
You can select a customer's language preference on their account page.

You can select a customer's language preference on their account page.

Email Translations

Recurly provides default email templates in all of the languages we support. This means that the New Subscription email can be sent immediately in Spanish upon enabling the Spanish language via one of our languages.

However, Recurly does not provide translations for every country. For example, the translations for all Spanish (Mexico, Spain, and United States) are the same after initially enabling a language. Merchants can make edits to each language/locale to make the templates specific to their use case.

To edit emails in different languages, you can change the language selector on the Email Templates page or on each individual email page you edit. The language selector looks like this:

You can customize your templates before enabling a language

We allow you to edit the templates for any language even if it is disabled. This allows you to customize your templates (previewing and sending test emails) before your customers start receiving emails.

All functionality for editing email templates applies to templates in individual languages. Please see the Email Template Customization documentation for more information on editing templates.

Settings are shared between languages

The template's settings (e.g. enabled/disabled, cc/bcc and from address) are shared between the languages. So if you disable the Renewal Reminder email, it will be disabled for all languages.

Email Parameters by Language

When you send emails, Recurly will adjust the email parameters to fit the country's formats. For example, English (United States) will send date formats as mm/dd/yyyy, whereas English (United Kingdom) will send them as dd/mm/yyyy. The following parameters will be formatted according to the conventions of each locale:

  • Dates and Date Intervals: ordering and translations of day, month, and year
  • Currencies: decimal and thousands separators and position of currency symbol ($1 234,50 vs. 1,234.50 $)
  • Quantities: thousands separators

In order to make sure these parameters function as you expect, we recommend using our Test Emails functionality before enabling emails to be sent to customers.

We do not provide translations for things like names or descriptions of plan, add-ons, etc. For example your company name, plan name, invoice terms and conditions, or line item description will not be translated into another language.

PDF Invoice Attachments

If you have enabled the Attach PDF option in the Invoice Settings, the attached PDF invoice will be translated into the same language as the email. For example, if the customer has selected Portuguese (Brazil), the invoice attachment will also be translated into Portuguese (Brazil).