Multi-currency and multi-language

SHOPLINE empowers merchants to expand their global reach by supporting multi-currency and multi-language sales for all products and services.

Through the Markets and Languages settings in the SHOPLINE Admin, merchants can easily set up their store for international selling. Meanwhile, SHOPLINE Payments enables merchants to implement multi-currency settlement and multi-language display, ensuring a seamless localized experience for customers throughout browsing and checkout.

When multi-currency and multi-language features are enabled, a country or region selector and a language selector must be displayed in the header, footer, or navigation drawer to allow customers to switch preferences at any time.

The following explains how to implement these features using localization components.

Country or region selector​

• Form requirements:
  • The selector must be placed within a form generated by the localization_form tag.
  • The form must include an input field with name="country_code".
  • Upon submission, the selected country or region code is sent to the backend.
• Data specifications:
  • Use localization.available_countries to iterate through all available countries or regions.
  • Access the currently active country or region via localization.country.
  • If a newly selected country or region does not support the current language, the system will automatically switch to that country or region's default language.

The following sample code demonstrates a country or region selector that allows customers to switch between different countries or regions.

{{#localization_form enctype="multipart/form-data" accept-charset="UTF-8"}}
  <select name="country_code" onchange="this.form.submit();">
    {{#for country in localization.available_countries}}
      <option value="{{country.iso_code}}" {{#if localization.country.iso_code == country.iso_code}}selected{{/if}}>
        {{country.name}}({{country.currency.iso_code}}
        {{country.currency.symbol}})
      </option>
    {{/for}}
  </select>
{{/localization_form}}

For details on using JavaScript to control option display and automate form submission, refer to the Handling form submission section below.

Language selector​

• Form requirements:
  • The selector must be placed within a form generated by the localization_form tag.
  • The form must include an input field with name="locale_code".
  • The option values are retrieved from iso_code in localization.available_languages.
• State tracking: Use localization.language to identify the currently selected language to highlight it or set it as the default in the UI.

The following sample code demonstrates a language selector that allows customers to switch between different languages.

{{#localization_form enctype="multipart/form-data" accept-charset="UTF-8"}}
  <select name="locale_code" onchange="this.form.submit();">
    {{#for language in localization.available_languages}}
      <option value="{{language.iso_code}}" {{#if localization.language.endonym_name == language.endonym_name}}selected{{/if}}>
        {{language.endonym_name}}
      </option>
    {{/for}}
  </select>
{{/localization_form}}

For details on using JavaScript to control option display and automate form submission, refer to the Handling form submission section below.

Handling form submission​

Since selectors are often custom components without an explicit submit button, you must monitor changes via script to submit the form. We recommend binding a change event to the country or region and language fields to trigger a unified submission function.

The following sample code demonstrates how to handle form submission for the country or region selector and language selector.

class LocalizationForm extends HTMLElement {
  constructor() {
    super();
    this.elements = {
      country: this.querySelector('input[name="country_code"]'),
      language: this.querySelector('input[name="locale_code"]'),
      form: this.querySelector('form'),
    };
    this.elements.country && this.elements.country.addEventListener('change', this.handleSubmit.bind(this));
    this.elements.language && this.elements.language.addEventListener('change', this.handleSubmit.bind(this));
  }
  handleSubmit(e) {
    e.preventDefault();
    this.elements.form.submit();
  }
}
defineCustomElement('localization-form', () => LocalizationForm);