If your site is on Relationship Invoicing and you have the Multi-Lingual Invoices feature enabled, Advanced Billing provides the ability to create custom translations for languages other than our current application default of English.
There are two facets to the Multi-Lingual Invoices feature:
- Customer Locale
- Language Customization
The final result will be a set of translations that can be customized to a specific region’s dialect. Additionally, you can create a standardized version of a language, for example a base “German” translation.
Customer Locale
When creating or editing a customer, you now have the ability to set a “Locale” for that specific customer. A full locale has two parts:
- Language: (Required) This is the language for this specific customer.
- Country/Region: (Optional) This is the country/region for this locale. (Note that this is not tied automatically to any addresses on file for the customer)
Add a locale for an existing customer on the customer edit page
You can view the customer’s locale on the customer details page as well as when editing the customer record, as seen in the images below.
View a customer's locale on the customer page
You can also see the customer's locale on the customer edit page
Language Customization
When visiting the Language Settings tab within the Settings section of the application, you have the ability to:
- Add a new Language
- Customize a Language (i.e. modify the existing translations)
- Configure a Language (i.e. change locale details)
- Set a Language as primary
- Delete a Language
Add A New Language
To add a new Language, click the “Add a Language” text in the Language Settings area. This will open a form for you to input a name for the custom Language in Advanced Billing, then select a language, such as Japanese, and a country/region, such as Japan.
Click `Add a Language` to create a new locale and set of translations
Below is an overview of each of the fields available per Language:
- Language Name (Required): You are free to name the language whatever you like. This name is what will appear in your Languages list on the settings page. We suggest naming similar to the full locale such as “Spanish - Mexico” for “es-MX” or “Spanish - Base” (es) for languages without a country/region selected.
- Language (Required): You can select from a list of languages within the drop-down.
- Country/Region (Not-Required): You can select from a list of countries/regions from the drop-down.
When creating a locale, set the name, language, and optionally the country/region
Please note that you cannot create Languages with duplicate locales. For example, if you already have a Language with a locale set as “es-MX”, you cannot create a second “Spanish” with “Spanish/Castilian” and “Mexico” as the Country/Region.
You may, however, have multiple Languages configured for the same base language with different regions selected. For the above example, it is possible to select another “Spanish/Castilian” language and set “Spain” as the Country/Region for a locale of “es-ES”.
Similarly, you could also create a base Spanish translation by creating a “Spanish - Base” with a language of “Spanish/Castilian” but without any country/region set. For more information on why this is useful, please review the Language Application section below
Customize a Language
By customizing a Language, you are providing over-rides in the specific language that will appear in place of the default English labels on invoices and credit notes for your customers if at least one of these conditions are met:
- their full locale matches the locale of this Language
- this Language is set as primary for your site, and the customer does not have a locale set that matches another of your Languages
A full discussion on this topic is below in the Language Application section.
We recommend visiting the custom translation documentation for more information on which words on an invoice can be customized and where they appear.
Configure a Language
If you’d like to change details about an existing Language – particularly the name, language, or region for the existing Language Locale – you can select “Configure Language”.
Please be aware of the constraints noted above, mainly that you may not duplicate an existing Locale.
Selecting "configure language" will allow you to modify the locale details of an existing language
Set a Language as Primary
Your primary Language will be the set of customized translations that your invoices and credit notes will default to if there is no matching Language Locale with the customer’s locale (or if the customer has no locale set). In other words, when new customers sign up, if they aren’t specifically given a specific locale, they will inherit the invoice translations from the primary Language.
Selecting "set as primary" will make this Language your site's primary Language
Delete a Language
You may delete a previously created Language. Please note that doing so is permanent and irreversible. If you attempt to delete a Language that is in use by active customers, the application will let you know how many customers you will be affecting prior to deletion. At this time we cannot provide a list of who would be affected, and may only return a count of them. Deleting a language that is in use by customers will result in a fallback to the next level of the hierarchy below. Please be cautious before you delete an in-use language.
When you go to delete a set of translations, you may see 3 different sets of dialog:
- If there are no customers currently using this set of translations you will see “You currently have no customers using” this translation and a note that it is safe to delete.
Deleting a set of translations not being used by any customers will let you know that it is safe.
- If you are deleting a set of translations that you have marked as primary, you will be informed that “Deleting the primary custom translations will affect all customers”.
Deleting the primary translations will warn you that it could affect all your customers.
- Finally if you are deleting a language that is in-use by customers you will be given a count of customers using that set of translations AND the fallback locale whose translations they will now see on their invoices.
Deleting a set of translations that is in use by customers will let you know how many customers and what their new fallback language will be.
None of these warnings will prevent you from deleting the language, so please be cautious when deleting.
Language Application
Once you’ve created some Languages, set one as primary, and have some customers with locales set, it’s important to understand how the Advanced Billing application will apply those Languages onto an invoice.
We will always try to use the closest match of a particular field to the customer’s locale. This means that translations from a matching Full-Locale field will be displayed if present, then a language-only field will be displayed if present. Then we will use the Advanced Billing provided defaults for that language if present. Then the site’s primary language translation of a field. Finally we would apply the Advanced Billing application default (English). Essentially, it’s possible for a given customer’s invoice to be pulling translations from multiple Languages based on a defined hierarchy.
Currently, Advanced Billing provides default values for the following languages: (English (en), Spanish (es)). We are working to add more full base language translations.
Here’s how the hierarchy works:
1. Full Locale Match:
When a customer's full locale matches a full locale language, that is the highest priority.
This is the highest priority of Custom Translations. If a customer’s locale matches exactly the Full Locale (e.g. es-MX) of a set of custom translations, we will display any over-rides for this language. If any values are not present here we would then fall back to:
2. Language Only Match:
When a customer's language only matches a locale language, that is the next priority.
This is the second highest priority of Custom Translations. If a customer’s locale (either full locale or language-only) matches a set of custom translations for ONLY that language code (e.g. “es-MX” would match with base “es”), we would then display any over-rides for this language bypassing any over-rides that existed for the full locale match above. If any values are not present here we would then fall back to:
3. Advanced Billing Provided Language Translations:
If Advanced Billing provides a set of full translations for a language, that is the final display for a matching customer locale language.
As noted above, we currently provide FULL base translations for the referenced languages. This is the third highest priority AND the final layer IF the customer’s locale-language matches a Advanced Billing-provided set of translations. We would display any base values here bypassing any over-rides from (1) and (2) that are present.
4. Site Primary Translations:
A customer with no locale set will receive the site primary translations (if one is set).
If (3) is not present for the customer’s locale language, then the next level of priority would be the set of custom translations determined by the merchant as the Site Primary. We would display any over-rides within the Site Primary bypassing any over-rides set in (1) and (2). If any values are not present here we would finally fall back to:
5. Advanced Billing Application Default:
Any values not present in the above hierarchy would default to the application default of English base values.
Language Application Example
I have a site that offers a product in Central America. I create a “Spanish - Base” Language and create over-rides for most of the fields on an invoice. At the same time, I have customers in many different countries: Mexico, Costa Rica, and Belize.
I set the locales on my customers appropriate to each one: “es-MX”, “es-CR”, and “es-BZ”.
For the most part, my existing “Spanish - Base” translations are fine for those customers, except for a few key fields such as “Billing Address” and “Shipping Address”.
I can then create Language Locales for “es-MX”, “ex-CR”, and “ex-BZ” and select “Customize Language” and create Country/Region over-rides just for those few address fields that need to be different for each Country/Region.
When those customers view their invoices, they will see the invoice using their Language Locale specific translations for the “Billing Address” and “Shipping Address” fields. But the “Spanish - Base” fields that have been set as primary are utilized everywhere else.
If that “Spanish - Base” primary does not have all of the fields with over-rides, then those customers will see the Advanced Billing Provided Spanish translations and that’s it.
If, however, this entire example was for Italian with no Advanced Billing provided Italian base translations, then these customers would see the Site Primary translations for missing values and finally the Advanced Billing Default English translations for any missing fields.
We are working on providing more default language specific translations and as they are available we will provide updates. For now, translations must be provided by users.