[{"value":"Implementing Country/Region and Language Selectors","id":"implementing-countryregion-and-language-selectors","hLevel":2,"level":1},{"value":"Country/Region Selector","id":"countryregion-selector","hLevel":2,"level":1},{"value":"Language Selector","id":"language-selector","hLevel":2,"level":1},{"value":"JavaScript Submission of the Localization Form","id":"javascript-submission-of-the-localization-form","hLevel":2,"level":1}]

Support for Multiple Currencies and Languages

Merchants can use SHOPLINE Payments to sell in multiple currencies and languages. This means customers can browse the store and checkout using their preferred currency and language.

Implementing Country/Region and Language Selectors

If merchants enable multiple currencies and languages, you should allow customers to choose their preferences. You can build the following components to provide this functionality to customers:

Country/Region Selector
Language Selector

You can include the country/region and language selectors in the header, footer, or navigation drawer.

Country/Region Selector

You can build a country/region selector to allow customers to manually choose their preferred currency. If the selected country/region does not support the current language selection, it will update to the default language of that country/region.

The selector needs to be placed within a localization form. You can create this form using the Handlebars form helper and the 'localization' parameter. The selector should also include an input attribute with name="country_code", and its value will be the selected country/region.

The countries/regions enabled by merchants can be accessed via the available_countries property under the localization object, and the currently selected country/region can be accessed via the country property.

The following example includes a button and a popup containing each country/region option:

{{#if localization.available_countries.size > 1}}
  <localization-form>
    {{#form 'localization' id="localization-form" enctype="multipart/form-data" accept-charset="UTF-8"}}
      <div class="dropdown-menu">
        <input type="hidden" name="country_code" value="{{ localization.country.iso_code }}">
        <button class="button button--secondary dropdown-menu__button" type="button">
          <span data-label>{{localization.country.name}} ({{localization.country.currency.iso_code}} {{localization.country.currency.symbol}})</span>
          <svg class="icon icon-arrow" width="10" height="10" viewBox="0 0 10 10" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M0.899486 3.44971L4.94974 7.49996L9 3.44971" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
          </svg>
        </button>
        <div class="dropdown-menu__list-wrapper top global-modal-border-shadow body4" hidden>
          <ul class="dropdown-menu__list list-unstyled">
            {{#for localization.available_countries as |country|}}
              <li>
                <a href="#" data-value="{{country.iso_code}}">{{country.name}} ({{country.currency.iso_code}} {{country.currency.symbol}})</a>
              </li>
            {{/for}}
          </ul>
        </div>
      </div>
    {{/form}}
  </localization-form>
{{/if}}

For a JavaScript example on managing the visibility of the options list and submitting the form upon selection, refer to the JavaScript Submission of the Localization Form.

Language Selector

You can build a language selector to allow customers to manually choose their preferred language.

The selector needs to be placed within a localization form. You can create this form using the Handlebars form helper and the localization parameter. The selector should also include an input attribute with name="language_code", and its value will be the selected language.

The available languages can be accessed via the available_languages property of the localization object, and the currently selected language can be accessed via the language property.

The following example includes a button and a popup containing each language option:

{{#if localization.available_languages.size > 1}}
  <localization-form>
    {{#form "localization" id="localization-form" }}
      <div class="dropdown-menu">
        <input type="hidden" name="locale_code" value="{{ localization.language.iso_code }}">
        <button class="button button--secondary dropdown-menu__button" type="button">
          <span data-label>{{ localization.language.endonym_name }}</span>
          <svg class="icon icon-arrow" width="10" height="10" viewBox="0 0 10 10" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M0.899486 3.44971L4.94974 7.49996L9 3.44971" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
          </svg>
        </button>
        <div class="dropdown-menu__list-wrapper top global-modal-border-shadow body4" hidden>
          <ul class="dropdown-menu__list list-unstyled">
            {{#for localization.available_languages as |language|}}
              <li>
                <a href="#" data-value="{{language.iso_code}}">{{language.endonym_name}}</a>
              </li>
            {{/for}}
          </ul>
        </div>
      </div>
    {{/form}}
  </localization-form>
{{/if}}

For a JavaScript example on managing the visibility of the options list and submitting the form upon selection, refer to the JavaScript Submission of the Localization Form.

JavaScript Submission of the Localization Form

Since your country/region or language selector is a custom element and there is no submit button in the form, you need to submit the form via JavaScript.

The following example is based on the previous Country/Region and Language selector examples:

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) {
    this.elements.form.submit();
  }
}
defineCustomElement('localization-form', () => LocalizationForm);