Skip to main content

Localization

Localization is the process of adapting your store for commerce in a specific country or region. This includes translating the user interfaces to a specific language, offering prices in the local currency, and showing time and dates in a format familiar to people from that region.

You can localize the Reflow toolkit to any language. All toolkit components can be fully translated and a wide range of currencies are supported.

Specifying a Localization File​

To translate Reflow, you need to specify a locale file when including the JS library. This will change the entire user interface of Reflow components, including labels, text prompts and error messages. Example:

<script
  src="https://cdn.reflowhq.com/v2/toolkit.min.js"
  data-reflow-project="999999"
  data-reflow-locale="/path/to/translation.json"
  defer
></script>

To create a translation, follow these steps:

  1. Download the en-US.json file. This is Reflow's default language file. You will use it as a starting point.
  2. Translate some or all of the phrases to your language of choice. This is covered in the next section.
  3. Upload the file to your server. For testing, you can use a local web server as well. Note that it needs to be hosted on the same domain and port as the rest of your website, otherwise the browser will block it due to CORS.
  4. In the script tag where you import the Reflow library CDN, add the data-reflow-locale parameter and point to the URL of your json, like in the example above.
  5. Check your browser's console for any error messages that may point you to potential problems with your translation.

Translation File Format​

The translation file is a simple JSON consisting of key/value pairs. The process of translating Reflow consists of rewriting the values to your language of choice.

// The default en-US.json in English
{
  "locale": "en-US",

  "shopping_cart": "Shopping Cart",
  "product": "Product",
  ...
}
// A localized example in French
{
  "locale": "fr-FR",

  "shopping_cart": "Panier",
  "product": "Produit",
  ...
}

Instructions​

  • The keys should not be changed. They are used by the library for matching UI elements with their localized text.
  • The values represent the actual content that is visible in the UI. They should be replaced with the translation in the chosen language.
  • All lines in the JSON (except for the locale property) are optional. You can omit the lines you don't wish to translate. In that case the default English equivalent will be used.
  • The locale line is special. It only accepts a standard ISO country-language tag. This is the locale used for formatting prices and dates, among other things.

Message Format​

The values in the JSON follow the standardized ICU message format. We won't be covering the entire standard here, only a couple of things you will need to know when writing translations.

String Interpolation​

Some of the phrases in the localization file support placeholder variables that will be replaced with their corresponding values.

"product.left_in_stock": "{numberItems} left in stock"

# numberItems = 10
# Displayed as "10 left in stock"

When translating these lines, make sure to keep the correct curly braces syntax and not to translate the text inside them.

"product.left_in_stock": "{numberItems} 剩余库存"

Including the placeholders in your translations is optional. If they are omitted, the localized string will be inserted in the UI without string interpolation.

Pluralization​

For messages where the final string depends on the value of a certain property, the plural ICU message syntax is used.

"A maximum of {max_qty} {product}
  {max_qty, plural,
    =1 {}
    other {s}
  }
can be purchased per customer."

# product = "Nvidia GPU"
# When max_qty = 1: "A maximum of 1 Nvidia GPU can be purchased per customer."
# When max_qty = 3: "A maximum of 3 Nvidia GPUs can be purchased per customer."

For more on the plural syntax check out to the ICU Message docs.

Translating Countries and Regions​

In some cases the Shopping Cart component can display select inputs for customers to choose their country and region (e.g. for shipping address). By default all the countries and their regions names are shown in English.

These can be translated by adding the geo property to the localization JSON. In it, you can define what names should be displayed for the countries and regions you wish to translate. Here is an example:

"geo": {
  "BE": {
    "country_name": "Belgique",
  },
  "DE": {
    "country_name": "Allemagne",
  },
  "CA": {
    "country_name": "Canada",
    "regions": {
      "AB": "Alberta",
      "BC": "Colombie-Britannique",
      "MB": "Manitoba",
      "NB": "Nouveau-Brunswick",
      "NL": "Terre-Neuve-et-Labrador",
      "NT": "Territoires du Nord-Ouest",
      "NS": "Nouvelle-Écosse",
      "NU": "Nunavut",
      "ON": "Ontario",
      "PE": "île du Prince-Édouard",
      "QC": "Québec",
      "SK": "Saskatchewan",
      "YT": "Yukon"
    }
  },
}

We recommend downloading our example file for the geo property in English. You can then remove the countries that are unnecessary for you store, translate the ones you need and move them to your localization file under the geo property.

Local Currency​

Reflow supports a wide array of currencies that can be used for everything in your store, including product prices and shipping costs. You can change the currency of your project from the general settings page.

For a full list of available currencies visit the Currency Support docs.

Translating Customer Emails​

Reflow offers the option to send automated emails to your customers when they place an order, complete payment or do other interactions with your store. These emails are in English by default but their content can be translated.

Visit the Email Content and Localization guide for more.