Skip to main content

Detect and set a visitor’s optimal localization

If you have multiple localized versions of a single store using Shopify Markets, then you should make sure that each visitor interacts with the optimal version of the store. Depending on the merchant’s shop configuration, search engines might be able to pre-localize visitors, and Shopify might automatically redirect visitors. However, it’s still possible for a visitor to be browsing in a context for a market that they aren’t actually located in.

This guide shows how to use the Ajax API to detect a visitor’s optimal localization and to update their current state.

Note

As a best practice, don’t try to prevent visitors from browsing in a context other than their detected optimum. GeoIP detection isn’t perfect, especially when visitors are using VPNs, and sometimes customers want to have a product shipped to somewhere other than their current location. Shopify’s checkout will ensure that the prices and product availability are appropriate for the shipping address the customer eventually chooses.

Anchor to RequirementsRequirements

  • You have more than one market configured on your Shopify store.

Anchor to Step 1: Query for browsing context suggestionsStep 1: Query for browsing context suggestions

To use the customer’s browser settings and IP address to determine if a shop offers a better localized experience, you can query for browsing context suggestions. You can request country or language suggestions, or both, and provide values that should be excluded from suggestions. The names of languages and countries will be returned in the suggested language if there is one, or the current storefront language if not.

Querying for browsing context suggestions

Request

await fetch(
window.Shopify.routes.root
+ 'browsing_context_suggestions.json'
+ '?country[enabled]=true'
+ `&country[exclude]=${window.Shopify.country}`
+ '&language[enabled]=true'
+ `&language[exclude]=${window.Shopify.language}`
).then(r => r.json());

JSON response

{
"detected_values": {
"country": {
"handle": "CA",
"name": "Canada"
}
},
"suggestions": [
{
"parts": {
"country": {
"handle": "CA",
"name": "Canada",
"confidence": 1,
"options": {
"US": "États-Unis",
"JP": "Japon",
"CA": "Canada"
}
},
"language": {
"handle": "fr",
"name": "français",
"confidence": 1,
"options": {
"en": "anglais",
"es": "espagnol",
"fr": "français",
"ja": "japonais"
}
}
},
"confidence": 1
}
]
}

Anchor to Step 2: Update the current localizationStep 2: Update the current localization

The returned suggestions can be used to update the current localization by submitting a localization form. For a full tutorial detailing how to build a country and language selector in themes, refer to Support multiple currencies and languages. The following example shows a minimal implementation of building and submitting a localization form in JavaScript:

function updateLocalization({country, language}) {
const formId = crypto.randomUUID();
const formHtml = `
<form id="${formId}" action="/localization" method="POST" hidden>
<input name="_method" value="PUT" />
<input name="country_code" value="${country}" />
<input name="language_code" value="${language}" />
</form>
`;
document.body.insertAdjacentHTML("beforeend", formHtml);
document.getElementById(formId).submit();
}

updateLocalization({country: "CA", language: "fr"});

Anchor to Next stepsNext steps

Was this page helpful?