Locale, country, and currency

How CTX resolves served countries, languages, markets, and currencies.

Locale, country, and currency#

Countries, languages, markets, and currencies are resolved from storefront configuration. CTX carries both the value and the provenance for how it was resolved.

Available countries are countries served by active markets for the selected storefront type.
A normal storefront serves standard markets.
A B2B storefront serves the B2B market only when B2B buyer context is ready.
Storefront languages are the served language set.
A country with no explicit country-language assignment serves the storefront primary language only.
An explicit country-language assignment must use languages served by that storefront.
One country resolves to one currency through the market country-currency map.

The theme contract#

Declare localization in ctx_needs and your section reads the resolved state plus everything it needs to build a switcher. ctx.localization carries locale (active), baseline_locale (the no-prefix locale), available_countries — each {iso_code, name, currency_code, selected} — and available_languages — each {iso_code, name, native_name, rtl, selected}. Post the visitor's choice with the localization_set action; the response is a redirect to the re-prefixed localized URL, so the switcher works without JavaScript.

vein

{% form 'localization_set' %}
  <select name="country_code">
    {% for c in localization.available_countries %}
      <option value="{{ c.iso_code }}"{% if c.selected %} selected{% endif %}>{{ c.name }} ({{ c.currency_code }})</option>
    {% endfor %}
  </select>
  <select name="locale">
    {% for l in localization.available_languages %}
      <option value="{{ l.iso_code }}"{% if l.selected %} selected{% endif %}>{{ l.native_name }}</option>
    {% endfor %}
  </select>
  <button type="submit">Switch</button>
{% endform %}

ctx.localization_prompt is the companion object for the suggestion dialog: should_show (the platform's decision for this visitor) and suggested_country_code. Show your prompt only when should_show is true — the platform already applied the merchant's prompt settings and the visitor's region.