> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluid.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> To sign a new merchant up for Fluid programmatically, run `fluid signup` from the Fluid CLI, or call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. Before authenticated calls are possible, the merchant must sign the agent in to the Fluid CLI with the emailed code and --shop set to the company's fluid_shop (which also confirms the signup), or open the emailed confirmation link and give the agent an API token.
> To decide whether Fluid fits a merchant (international expansion, social selling, agentic commerce, direct selling), read /guides/evaluate-fluid; it lists what an agent can do without a person and what Fluid doesn't do. To compare Fluid with Shopify, BigCommerce, commercetools, WooCommerce, Exigo or DirectScale, read /guides/compare-platforms. Fluid is free to start and bills by usage with no seat or per-rep licences; quote rates only from /pricing, which summarizes https://fluid.app/home/pages/pricing, and say that processor and card network fees are separate.
> Every live Fluid storefront serves /llms.txt, /agents.md, .md and .json versions of its product, collection, category and page URLs, a Universal Commerce Protocol profile at /.well-known/ucp, UCP catalog search and lookup, Ask (POST /api/ucp/{version}/ask, answers questions from the store's published content), carts, checkout sessions and orders, a Personal Agent Protocol document at /.well-known/poppy.json, and an A2A Agent Card at /.well-known/agent-card.json with a JSON-RPC endpoint at /api/a2a. A checkout session completes inside the agent with Google Pay when the store's profile lists the com.google.pay payment handler; otherwise hand the shopper the continue_url to hosted checkout. A member's share link is /<username>/products/<slug>; see /concepts/agentic-commerce, /concepts/poppy, /concepts/ucp and /concepts/a2a.
> After signup, to launch a merchant's store (back-office sync, payments onboarding, store setup, a theme copied from their current site, and a preview link before billing), follow /api/agent-launch.
> To host a small project on Fluid (a landing page, event page, calculator or dashboard), follow /sites/quickstart: npm create @fluid-app/fluid-site my-site (or npx @fluid-app/create-fluid-site my-site), fluid login, then fluid deploy prints the public URL. Launch a Site unless the project needs a custom domain, server rendering or heavy server code, which make it an App (a Mist app); /sites/site-or-app has the rule, and POST /api/company/v2026-10/project-launch-recommendations applies it. With only the Fluid MCP server (its Site write tools are limited to Fluid root admins today; see /sites/deploy-from-claude), use site_create, then site_deploy (from a chat with no shell, in one call with the files inline: site_template_get for a starter, then site_deploy with each path's content; or a built folder in two calls: send the manifest, PUT the listed uploads, call again with the bundle_id to get the url), then, only after the person confirms they want it public, site_visibility_set. site_logs, site_traffic, site_env_list/set/unset, site_seo_get/set and the site_branch tools cover logs, traffic, env vars, SEO and preview branches; a member builds their own Sites with the my_site_* tools. The MCP site_deploy tool publishes server functions sent inline that import nothing; publish functions with imports, and convert a Site to an App, with the fluid sites CLI. A Site can serve light server code: each functions/<name>.ts, declared in config/functions.json with access public, signed_in or key (and an optional UTC cron schedule), answers at /api/<name> on the Site's own host; publish it with fluid deploy, or inline through the MCP site_deploy tool when it imports nothing. See /sites/functions and /sites/rest-api.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. The same applies to /api/company/v1 and /api/v1/... paths: prefer a newer documented equivalent, and use one only when none exists (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only on an operation whose spec documents those params — mostly the unversioned company-v0 admin surface, plus some lists on other surfaces, versioned ones included; page every other list with cursors.
> To create a URL redirect, create a custom route on the Sitemap: POST /api/theme_region_rules with redirect_type redirect, a redirect_url, region_code default, route_kind non_credit and redirect_status_code 301 or 302. See /themes/custom-routes#create-a-redirect-with-the-api. Never use /api/redirects; those legacy redirects are no longer used, and the admin's Sitemap screen doesn't show them.
> Fluid has three navigation APIs; don't mix them up. Storefront website menus (navigation bars, footers) are /api/menus and nested menu_items, in api-reference/content-v0.yaml (API Reference: Website > Navigation menus), with a how-to in themes/navigation-menus; their list uses flat page/per_page pagination. The Fluid mobile app's navigation is /api/v2/mobile_navigations, in api-reference/mobile-v2.yaml (API Reference: Mobile app > Navigation); its list also uses page/per_page. Portal navigations belong to a portal definition (Fluid OS), in api-reference/fluid-os-v0.yaml (API Reference: Portal > Portal navigation), and each has a platform of web or mobile.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated except two operations that take no credential, POST /api/company (create a company) and GET /api/agreements/{id} — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country).
> api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.
> Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other.
> For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces.
> Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings.
> Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties.
> Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables.
> A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation.
> The Help Center (/help/...) is for merchants, admins and reps using Fluid. Its admin pages mirror the admin's routes: the screen at admin.fluid.app/settings/taxes is documented at /help/admin/settings/taxes. Use the Help Center for how-to questions about the admin, and the Developer Platform and API Reference for building integrations.
> Help Center pages describe what a company admin sees. A reader's role can hide screens and actions; admins manage roles on Settings > Roles (/help/admin/settings/roles). If someone can't find a screen or button, their role's permissions are the first thing to check.
> Send people who need Fluid support to /help/getting-help. Don't invent support email addresses, phone numbers or response times.

# Regional languages

> How Fluid serves Canadian French, Mexican Spanish and Brazilian Portuguese, with or without their base languages: tags, how a page picks its language, fallback on every surface, caching, audiences, the release gate, and how to add one to a company with the API.

A regional language is a regional version of a language Fluid already supports. A company can offer Canadian French next to French, for example. It can also offer Canadian French without French. 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:

| Tag | Name in Fluid | Base language |
| - | - | - |
| `fr-CA` | Français (Canada) | `fr`, French |
| `es-MX` | Español (México) | `es`, Spanish |
| `pt-BR` | Português (Brasil) | `pt`, Portuguese |

> [!NOTE]
>
> 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](https://docs.fluid.app/help/getting-help.md).

## 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 doesn't need its base language.** A company can turn on Canadian French while French is off. See [Offer only the regional language](#offer-only-the-regional-language).
* **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.**

A company may offer a regional language without its base. Then a request for the base language, such as `fr`, gets the regional language, such as `fr-CA`. This holds for the query parameter, a saved cookie and the browser. A browser that asks for `fr-CA` at a company that offers `fr` but not `fr-CA` still gets `fr`.

The language cookies look like this:

| Cookie | Holds | Example |
| - | - | - |
| `fluid_locale` | The language, an underscore, then the country | `fr-ca_CA`, or `fr-ca_US` for a shopper reading Canadian French in the United States |
| `fluid_language` | The language tag | `fr-ca` |
| `locale` | The language tag. Fluid saves it when a query parameter picks the language, when it replaces a saved language the company no longer offers, or when it serves a regional language in place of its base | `fr-CA` |

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](https://docs.fluid.app/themes/navbar-locale-selector.md).

## 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.
* **A request for a base language served in its regional language is cached under the regional language.** Fluid saves `fr-CA` for a browser that asks for `fr` at a company that offers only `fr-CA`. The page is cached under `fr-CA`, never under `fr`.
* **Language query parameters skip the cache.** A URL with `lang` or `locale` always renders fresh. See [Query parameters and caching](https://docs.fluid.app/themes/query-parameters-and-caching.md).
* **Turning a language off clears its cached pages.**
* **Turning on a regional language while its base is off clears the base language's cached pages.** French browsers then get Canadian French, not pages cached in another language.

## Where the fallback applies

Every surface reads the regional language first. Where text is missing, it reads the base language, then English.

| Surface | What a `fr-CA` reader sees where Canadian French text is missing |
| - | - |
| Storefront content: products, media, categories, collections, posts, pages, playlists and enrollment packs | The French text, then the English text. This covers rich text and images set per language. |
| Lists filtered by language | A list filtered to `fr-CA` also includes records that have a French title. |
| Translated metafield values | The French translation, then the English translation, then the original value. If French is the store's default language, the original value comes straight after Canadian French. |
| Theme text from the `t` filter | `locales/fr.json`, then `locales/en.json`, then Fluid's built-in text. See [Regional theme text](https://docs.fluid.app/themes/developer-guide.md#regional-languages). |
| Fluid's built-in text, such as system emails and error messages | Fluid's Canadian French wording where it has one, then French, then English. |
| Checkout | Fluid's Canadian French checkout wording where it has one, then French, then English. |
| Country names | The French country name. |
| FairShare widgets, such as the cart and chat | The French widget text. |

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.

## Offer only the regional language

A company can offer a regional language while its base language is off. A store for Canada, for example, can offer Canadian French and English, with French off.

* **Shoppers can't choose French.** The language selector lists Canadian French and the company's other languages.
* **The fallback still reads French.** Where Canadian French has no text, Fluid shows French, then English. The French comes from French text the company already has, the theme's `locales/fr.json`, and Fluid's built-in French text.
* **A visitor who asks for French gets Canadian French.** A browser that asks for `fr` or `fr-FR`, a `?locale=fr` link, or a saved `fr` language all get `fr-CA`. Fluid then saves `fr-CA` in the `locale` cookie.
* **Anything aimed at French still reaches Canadian French readers.** Matching follows the language, not the company's list. See [Audiences](#audiences).
* **New wording goes under `fr-CA`.** A save with `lang=fr` returns `422` while French is off.
* **Translate in full when there's no French text.** Where a product or page has no French text, Canadian French readers see English. Translate it into Canadian French like any other language. See [Add a language](https://docs.fluid.app/setup/add-a-language.md).

## The release gate

The `regional-languages` release gate decides which companies can turn a regional language on. Fluid turns it on per company.

| | Gate off | Gate on |
| - | - | - |
| The company's language list | Regional languages are left out, except any the company already has | Regional languages are listed |
| Turning one on | Refused as an unknown language | Allowed, whether or not its base language is on |

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 turn a base language off while its regional language is on. 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-MX` or `pt-BR`. The base language can be on or off.

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](https://docs.fluid.app/api-reference/languages/list-company-languages.md), [Configure company language](https://docs.fluid.app/api-reference/languages/configure-company-language.md) and [Remove company language](https://docs.fluid.app/api-reference/languages/remove-company-language.md).

**1. List the languages and find the regional tag**

```bash theme={null}
curl "https://api.fluid.app/api/settings/languages" \
  -H "Authorization: Bearer <token>"
```

Find the row whose `iso` is `fr-CA`. Note its `id`, and whether `active_in_company` is `true`. Look ids up by `iso` every time. Ids aren't the same in every environment.

```json theme={null}
{
  "languages": [
    { "id": 7, "name": "Français", "iso": "fr", "company_users_count": 214, "active_in_company": true },
    { "id": 61, "name": "Français (Canada)", "iso": "fr-CA", "company_users_count": 0, "active_in_company": false }
  ],
  "meta": { "request_id": "c4f1b9e2-7a3d-4e8b-9f21-5d6a0b3e8c47", "timestamp": "2026-11-20T15:32:08Z" }
}
```

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 regional language on**

Skip this step when `fr-CA` already has `active_in_company: true`. Otherwise send its `id`:

```bash theme={null}
curl -X POST "https://api.fluid.app/api/settings/languages" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 61}'
```

A `200` response returns the language:

```json theme={null}
{
  "language": { "id": 61, "name": "Français (Canada)", "iso": "fr-CA", "company_users_count": 0, "active_in_company": true },
  "meta": { "request_id": "8d2e6f14-3b9a-4c71-a5e0-2f7c9d1b4e86", "timestamp": "2026-11-20T15:33:41Z" }
}
```

**3. Check the result**

```bash theme={null}
curl "https://api.fluid.app/api/settings/languages?active=true" \
  -H "Authorization: Bearer <token>"
```

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

Don't turn `fr` on just so Canadian French has something to fall back to. The fallback works while `fr` is off.

### When a request fails

Both errors carry `error_message` and an `errors` value that says why.

| Response | `errors` | What it means | What to do |
| - | - | - | - |
| `404` | `{"language": ["Language not found"]}` | The gate is off for the company, or the `id` isn't a language. | Check the `id`. If it's right, ask Fluid support to turn the gate on. |
| `422` | A list of messages | The language is already on. | Nothing. Read `active_in_company` first, so you send only what's off. |

The exception is a regional language that's already on while the gate is off. It answers `404`, not `422`.

### Turn a regional language off

Send `DELETE /api/settings/languages/{id}` with the language's `id`, the same `id` as in the list. The order of a base language and its regional language doesn't matter. Turning `fr` off while `fr-CA` is on works, and Canadian French keeps working. You still can't turn off the company's default language, or a language that a mobile app page or mobile app navigation is limited to.

The Fluid CLI wraps these calls. `fluid translations enable fr-CA --yes` turns on Canadian French. See [Add a language](https://docs.fluid.app/setup/add-a-language.md).

## Give it its own wording

Save only the text that differs from the base language. Everything else already shows the base language. When the base language has no text for an item, see [Offer only the regional language](#offer-only-the-regional-language).

* **Storefront resources:** a translation `PATCH` with `lang=fr-CA`, such as `PATCH /api/v202604/company/products/{id}?lang=fr-CA`. See [Translations](https://docs.fluid.app/storefront/translations.md).
* **Metafield values:** the metafield translation endpoints, with `fr-CA` as the language. See [Translate metafields](https://docs.fluid.app/storefront/metafields.md#translate-metafields).
* **Theme text:** a `locales/fr-CA.json` file with only the keys that differ. See [Regional theme text](https://docs.fluid.app/themes/developer-guide.md#regional-languages).

```bash theme={null}
curl -X PATCH "https://api.fluid.app/api/v202604/company/products/60311?lang=fr-CA" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"product": {"title": "Mélange de betteraves du Québec"}}'
```

> [!WARNING]
>
> Don't machine-translate the whole store into a regional language while the company has French text. 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. A regional language doesn't need its base language. Turn on only the languages the company wants to offer.
4. Don't turn the base language on just for the fallback. The fallback works while the base language is off.
5. Turn a base language and its regional language on and off in any order.
6. Look up language ids by `iso` with `GET /api/settings/languages`. Never hard-code an id.
7. Read `active_in_company` before you send a `POST`. Send one only for a language that's off. A `422` from the `POST` usually means the language is already on.
8. If the regional tag isn't in the company's language list, the release gate is off. Don't retry. Ask Fluid support.
9. A `404` when you turn on a regional language with a correct `id` means the gate is off.
10. Where the base language has text, save regional text only where the wording differs.
11. Don't run machine translation over a whole regional language while the company has base-language text.
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.

## Related pages

* [Languages in the admin](https://docs.fluid.app/help/admin/settings/languages.md#regional-languages)
* [Translations](https://docs.fluid.app/storefront/translations.md)
* [Translate metafields](https://docs.fluid.app/storefront/metafields.md#translate-metafields)
* [Localization in themes](https://docs.fluid.app/themes/developer-guide.md#localization)
* [Add a language](https://docs.fluid.app/setup/add-a-language.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.