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-TWis Traditional Chinese, a different script fromzh. It keeps its own rules and never readszhtext.
Tags
A regional tag is a BCP 47 language tag: the language in lowercase, a hyphen, then the region in uppercase. Write it asfr-CA, es-MX or pt-BR.
- Send the exact tag to the storefront API. It matches the
langvalue exactly, solang=fr-caisn’t the same aslang=fr-CA. A read ignoresfr-caand answers in the default language. A write refuses it with422. - Cookies and browser headers may use any case. Fluid reads
fr-caandFR-CAasfr-CAthere. - A hyphen, never an underscore.
fr_CAisn’t a regional tag. In thefluid_localecookie the underscore separates the language from the country. - Other regional tags aren’t regional languages. Fluid reads an unlisted tag such as
fr-BEoren-GBin a browser’s language list as its base language. A read with an unlisted tag inlangorlocaleignores 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.- The
localequery parameter, orlangwhen there’s nolocale. Fluid saves the choice in thelocalecookie. - A saved language cookie:
fluid_locale, thenfluid_language, thenlocale. Fluid reads only the first of these cookies that exists. If the company doesn’t offer that language, Fluid moves on to the browser. - The browser’s
Accept-Languageheader. Entries are ranked by weight, ties keep the header’s order, and entries weightedq=0are dropped. For each entry, Fluid tries the regional language first, then its base. A browser that sendsfr-CA,fr;q=0.9getsfr-CAwhen the company offers it, andfrwhen it doesn’t. - The company’s default language.
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-CApages never mix withfrpages. - 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-MXorpt-BR. Fluid renders their page fresh and doesn’t cache it. The response carriesX-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
langorlocalealways 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-CAalso matches anything aimed atfr. This covers mobile app pages, mobile app navigation, mobile app share pages and widgets. - Where a target aimed at
fr-CAand one aimed atfrboth apply, thefr-CAone wins. Widgets still follow their usual priority. - A person whose language is
frdoesn’t match a target aimed only atfr-CA. - A messaging audience aimed at
fralso reaches members whose language isfr-CA, once the company has turnedfr-CAon. An audience aimed atfr-CAreaches onlyfr-CAmembers.
The release gate
Theregional-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, usees 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
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.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 A
fr-CA already has active_in_company: true. Otherwise send its id:200 response returns the language:4
Check the result
fr-CA. Shoppers can choose it, and translations can be saved to it.When a request fails
Both errors carryerror_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
SendDELETE /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
PATCHwithlang=fr-CA, such asPATCH /api/v202604/company/products/{id}?lang=fr-CA. See Translations. - Metafield values: the metafield translation endpoints, with
fr-CAas the language. See Translate metafields. - Theme text: a
locales/fr-CA.jsonfile with only the keys that differ. See Regional theme text.
Rules
Follow these when you add or change a regional language.- A regional language is one of
fr-CA,es-MXorpt-BR. No other tag is regional. - Write the tag with a hyphen and an uppercase region:
fr-CA. Send exactly that to the API. - Turn the base language on before its regional language.
- Turn the regional language off before its base language.
- Look up language ids by
isowithGET /api/settings/languages. Never hard-code an id. - Read
active_in_companybefore you send aPOST. Send one only for a language that’s off. - If the regional tag isn’t in the company’s language list, the release gate is off. Don’t retry. Ask Fluid support.
- A
404when you turn on a regional language with a correctidmeans the gate is off. - A
422that names the base language means the base language is off. Turn it on, then retry once. - Save regional text only where the wording differs from the base language.
- Don’t run machine translation over a whole regional language.
- Name a regional theme file with the exact tag, such as
locales/fr-CA.json. - 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.
- Set a shopper’s language with the FairShare SDK’s
updateLocaleSettings(), never by writing cookies.