---
title: Detect and set a visitor’s optimal localization
description: This guide shows how to use the Ajax API to detect a visitor’s optimal localization and to update their current state.
source_url:
  html: https://shopify.dev/docs/storefronts/themes/markets/localization-discovery
  md: https://shopify.dev/docs/storefronts/themes/markets/localization-discovery.md
---

ExpandOn this page

* [Requirements](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#requirements)
* [Step 1: Query for browsing context suggestions](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#step-1-query-for-browsing-context-suggestions)
* [Step 2: Update the current localization](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#step-2-update-the-current-localization)
* [Next steps](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#next-steps)

# Detect and set a visitor’s optimal localization

If you have multiple localized versions of a single store using [Shopify Markets](https://help.shopify.com/manual/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.

***

## Requirements

* You have more than one [market](https://shopify.dev/docs/api/admin-graphql/latest/objects/Market) configured on your Shopify store.

***

## Step 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

```javascript
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

```json
{
  "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
    }
  ]
}
```

***

## Step 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](https://shopify.dev/docs/storefronts/themes/markets/multiple-currencies-languages). The following example shows a minimal implementation of building and submitting a localization form in JavaScript:

```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"});
```

***

## Next steps

* Learn how to [detect and set a user’s optimal localization when building a Hydrogen shop](https://shopify.dev/docs/storefronts/headless/hydrogen/markets/locale-detection).
* Learn how to [add a country and language selector to your theme](https://shopify.dev/docs/storefronts/themes/markets/multiple-currencies-languages) so customers can choose their own locale preference.
* Get an overview of [the localized experiences that are possible with Shopify Markets](https://shopify.dev/docs/apps/build/markets), and how to effectively support them.
* Explore an example of using the Storefront API to [load a shop’s supported countries and languages](https://shopify.dev/docs/api/storefront/latest/queries/localization#examples-Load_the_countries_a_shop_sells_to_and_the_supported_languages_for_each).
* Use the GraphQL Admin API to [translate an online store’s content](https://shopify.dev/docs/apps/build/markets/manage-translated-content).

***

* [Requirements](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#requirements)
* [Step 1: Query for browsing context suggestions](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#step-1-query-for-browsing-context-suggestions)
* [Step 2: Update the current localization](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#step-2-update-the-current-localization)
* [Next steps](https://shopify.dev/docs/storefronts/themes/markets/localization-discovery#next-steps)