Skip to main content
A regional language is a regional version of a language Fluid already supports. A company can offer Canadian French next to French, for example. Shoppers and members pick it like any other language. Wherever it has no wording of its own, Fluid shows the base language, then English. Fluid offers three regional languages:
Regional languages are behind the regional-languages release gate. A company can turn one on only after Fluid turns the gate on for it. To ask for it, contact support.

How a regional language works

  • It’s a language of its own. It has its own row in the company’s languages. People choose it, and translations are saved under its tag.
  • It holds only the wording that differs. Where it has no text of its own, Fluid reads the base language, then English. Nothing is copied, so a later French edit shows in Canadian French at once.
  • Fallback works per field and per key. A product with a Canadian French title and no Canadian French description shows the Canadian title and the French description.
  • Its own text wins for good. Once you save Canadian French text for a field, a later French edit to that field no longer reaches Canadian French shoppers. Update both.
  • Chinese isn’t regional. zh-TW is Traditional Chinese, a different script from zh. It keeps its own rules and never reads zh text.

Tags

A regional tag is a BCP 47 language tag: the language in lowercase, a hyphen, then the region in uppercase. Write it as fr-CA, es-MX or pt-BR.
  • Send the exact tag to the storefront API. It matches the lang value exactly, so lang=fr-ca isn’t the same as lang=fr-CA. A read ignores fr-ca and answers in the default language. A write refuses it with 422.
  • Cookies and browser headers may use any case. Fluid reads fr-ca and FR-CA as fr-CA there.
  • A hyphen, never an underscore. fr_CA isn’t a regional tag. In the fluid_locale cookie the underscore separates the language from the country.
  • Other regional tags aren’t regional languages. Fluid reads an unlisted tag such as fr-BE or en-GB in a browser’s language list as its base language. A read with an unlisted tag in lang or locale ignores it.

How a storefront page picks its language

Fluid picks the language of each storefront page in this order. It takes the first language that the company has turned on.
  1. The locale query parameter, or lang when there’s no locale. Fluid saves the choice in the locale cookie.
  2. A saved language cookie: fluid_locale, then fluid_language, then locale. Fluid reads only the first of these cookies that exists. If the company doesn’t offer that language, Fluid moves on to the browser.
  3. The browser’s Accept-Language header. Entries are ranked by weight, ties keep the header’s order, and entries weighted q=0 are dropped. For each entry, Fluid tries the regional language first, then its base. A browser that sends fr-CA,fr;q=0.9 gets fr-CA when the company offers it, and fr when it doesn’t.
  4. The company’s default language.
The language cookies look like this: The FairShare SDK writes fluid_locale and fluid_language when you call updateLocaleSettings(). It writes the language in lowercase and the country in uppercase. Don’t write these cookies yourself. Use the SDK, as in Navbar locale selector.

Caching

  • Each regional language has its own cached pages. When a cookie names the language, cached pages are kept per country and per language, so fr-CA pages never mix with fr pages.
  • A browser-only regional language skips the cache. Suppose a visitor has no language cookie, and their browser’s first choice is fr-CA, es-MX or pt-BR. Fluid renders their page fresh and doesn’t cache it. The response carries X-CDN-Cache: SKIP. This holds at every company, whether or not it offers the language. Once the visitor saves a language, their pages are cached again.
  • Language query parameters skip the cache. A URL with lang or locale always renders fresh. See Query parameters and caching.
  • Turning a language off clears its cached pages.

Where the fallback applies

Every surface reads the regional language first. Where text is missing, it reads the base language, then English. Prices and Fluid’s built-in date formats look the same as in the base language. Checkout is the exception for dates and point amounts: it formats them in the regional style, such as 2026-11-20 for fr-CA.

Audiences

Anything you limit by language treats a regional language as part of its base:
  • A person whose language is fr-CA also matches anything aimed at fr. This covers mobile app pages, mobile app navigation, mobile app share pages and widgets.
  • Where a target aimed at fr-CA and one aimed at fr both apply, the fr-CA one wins. Widgets still follow their usual priority.
  • A person whose language is fr doesn’t match a target aimed only at fr-CA.
  • A messaging audience aimed at fr also reaches members whose language is fr-CA, once the company has turned fr-CA on. An audience aimed at fr-CA reaches only fr-CA members.

The release gate

The regional-languages release gate decides which companies can turn a regional language on. Fluid turns it on per company. The gate controls only turning a regional language on. If Fluid turns the gate off later, regional languages the company already has stay on and keep working. Whatever the gate says:
  • You can’t turn a base language off while one of its regional languages is on. Turn the regional language off first.
  • You can’t turn the company’s default language off.

Add a regional language with the API

These steps turn on Canadian French. For Mexican Spanish or Brazilian Portuguese, use es and es-MX, or pt and pt-BR. You need a company Bearer token with permission to update Languages. Every request goes to https://api.fluid.app with Authorization: Bearer <token>. The reference pages are List company languages, Configure company language and Remove company language.
1

List the languages and find both tags

Find the rows whose iso is fr and fr-CA. Note each one’s id, and whether active_in_company is true. Look ids up by iso every time. Ids aren’t the same in every environment.
If fr-CA isn’t in the list, the gate is off for the company. Stop, and ask Fluid support to turn it on.
2

Turn the base language on, if it's off

Skip this step when fr has active_in_company: true. Otherwise send its id:
3

Turn the regional language on

Skip this step when fr-CA already has active_in_company: true. Otherwise send its id:
A 200 response returns the language:
4

Check the result

The list now includes fr-CA. Shoppers can choose it, and translations can be saved to it.

When a request fails

Both errors carry error_message and an errors.language list that says why. A POST for a language that’s already on also fails with 422. The exception is a regional language while the gate is off, which answers 404. Read active_in_company first, so you send only what’s off. The 422 for a missing base language looks like this:

Turn a regional language off

Send DELETE /api/settings/languages/{id} with the language’s id, the same id as in the list. Turn off fr-CA before fr. Turning fr off while fr-CA is on fails with 422, and errors.language says Remove the regional languages of this language first. The Fluid CLI wraps these calls. fluid translations enable fr fr-CA --yes turns on French, then Canadian French. See Add a language.

Give it its own wording

Save only the text that differs from the base language. Everything else already shows the base language.
  • Storefront resources: a translation PATCH with lang=fr-CA, such as PATCH /api/v202604/company/products/{id}?lang=fr-CA. See Translations.
  • Metafield values: the metafield translation endpoints, with fr-CA as the language. See Translate metafields.
  • Theme text: a locales/fr-CA.json file with only the keys that differ. See Regional theme text.
Don’t machine-translate the whole store into a regional language. The CLI’s fluid translations missing fr-CA report lists every item that has no Canadian French text of its own, even when shoppers already see French. Saving a translation for each one copies the French text into Canadian French, and later French edits stop reaching those fields.

Rules

Follow these when you add or change a regional language.
  1. A regional language is one of fr-CA, es-MX or pt-BR. No other tag is regional.
  2. Write the tag with a hyphen and an uppercase region: fr-CA. Send exactly that to the API.
  3. Turn the base language on before its regional language.
  4. Turn the regional language off before its base language.
  5. Look up language ids by iso with GET /api/settings/languages. Never hard-code an id.
  6. Read active_in_company before you send a POST. Send one only for a language that’s off.
  7. If the regional tag isn’t in the company’s language list, the release gate is off. Don’t retry. Ask Fluid support.
  8. A 404 when you turn on a regional language with a correct id means the gate is off.
  9. A 422 that names the base language means the base language is off. Turn it on, then retry once.
  10. Save regional text only where the wording differs from the base language.
  11. Don’t run machine translation over a whole regional language.
  12. Name a regional theme file with the exact tag, such as locales/fr-CA.json.
  13. Leave a regional key out of a theme file instead of giving it an empty value. An empty value prints a blank space, not the base language’s text.
  14. Set a shopper’s language with the FairShare SDK’s updateLocaleSettings(), never by writing cookies.