Support multiple currencies and languages

To support multiple currencies and languages in your theme, you'll use the following:

• The form object
• The localization object

If a merchant has enabled multiple currencies and/or languages, then you should give customers the ability to select their preference. You can build the following components to give customers this ability:

• A country selector
• A language selector

You might include a country and/or language selector in your header or footer, or inside of a navigation drawer. For more detailed placement recommendations, and to learn about best practices for styling country and language selectors, refer to the UX guidelines.

You can build a country selector to allow customers to manually choose their preferred currency. If the currently selected language is not supported by the selected country, it will be updated to the default language for that country.

The selector needs to be placed inside a localization form. This form can be created using the Liquid form tag and the 'localization' parameter. The selector also needs to contain an input with the attribute name="country_code", whose value will be the selected country.

The shop's enabled countries are accessible through the available_countries attribute of the localization object, and the currently selected country is accessible through the country attribute.

The following example includes a button and a popover containing each country option:

For an example of JavaScript that manages the visibility of the option list and submits the form on selection, refer to JavaScript submission of the localization form.

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

The selector needs to be placed inside a localization form. This form can be created using the Liquid form tag and the 'localization' parameter. The selector also needs to contain an input with the attribute name="language_code", whose value will be the selected language.

The available languages are accessible through the available_languages attribute of the localization object, and the currently selected language is accessible through the language attribute.

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

For an example of JavaScript that manages the visibility of the option list and submits the form on selection, refer to JavaScript submission of the localization form.

Because your country or language selector is a custom element and there's no submit button included in the form, you need to submit the form through JavaScript.

The following example is based on the previous country and language selector examples:

Stores can have dynamic URLs generated for them when they sell internationally or in multiple languages.

• When an additional locale (language) is published on a domain, Shopify automatically creates a URL path for it. For example, if a shop's primary URL is shop.com, and a french (fr) locale is published on that domain, then the URL shop.com/fr is automatically created.
• When a merchant creates a new market, Shopify creates a URL path for that market. For example, if a shop's primary market is the United States and primary locale is English on shop.com, when a Canada market is created, then the URL shop.com/en-ca is created.

Given these possible dynamic changes in URL structure, you should avoid hardcoding URLs. If you’ve hardcoded a URL like /cart in a link or Ajax request, then visitors browsing in another language or market context will be forced back to the domain defaults. This means they may see the wrong language or currency. Instead, use the following instructions to build dynamic URLs in Liquid or in JavaScript.

Use one of the following approaches to build dynamic URLs with Liquid:

• The url attribute of any applicable Liquid objects
• The routes object

If a merchant has English and French locales, then the cart URL could be /cart or /fr/cart, respectively. The following example shows how to link to the cart page in the currently selected locale.

You can build dynamic URLs in JavaScript by basing them off of the dynamic root route accessible on the window object, window.Shopify.routes.root. This value will always end in a /. For instance, if a merchant has a Canadian market in addition to their primary, window.Shopify.routes.root could return "/en-ca/" when a visitor is accessing that market’s subfolder.

The following example shows how to make an Ajax request to the cart while preserving the current market’s pricing:

In addition to providing options for customers to select a country and/or language, you also need to ensure that search engines return localized content and prices for customers.

Shopify automatically includes hreflang tags through the content_for_header object. You can also return localized prices by including, or extending, structured data in your theme.

When outputting structured data for products, you need to ensure that the priceCurrency property is set to reflect the cart currency, rather than the shop's currency.

For example: