Multi-Locale Guide

Setting up your locales

Locales are configured under Settings → Locales. Adding, renaming, reordering and disabling locales is covered in Locales. This guide assumes your locales already exist, and focuses on what happens after that.

Two things about locale setup matter specifically when you are building against the API.

The locale code is what your code will use. The Locale Region dropdown assigns a standard code (for example es-mx for Mexico). If you need a non-standard code, tick Custom Locale ID and define your own. Whatever code ends up here is the exact string your API requests must use.

The region dropdown searches by code, not by language name. Typing Spanish returns nothing. Type es to see all Spanish-speaking regions, or es-mx to jump straight to Mexico.

The Add Locale dialog, showing the Locale Region dropdown and the Locale Name field

Note: If you get an error when creating a locale, your license may not support additional locales. Contact support@agilitycms.com.

Choosing your locale context strategy

When building your front end, you need to decide how locale context is determined for incoming requests. There are three common approaches.

1. Locale code in the URL

The locale code is the first path segment:

https://mysite.com/en-us/about-us
https://mysite.com/es-mx/about-us

This is the most common approach for JAMstack sites. It makes the active locale explicit and crawlable by search engines.

JAMstack / Next.js: locale routing is handled in your application code. See Multi-Locale Support with Next.js for a full implementation guide.

Legacy .NET sites: locale-in-URL routing must be enabled under Settings → Development Framework.

2. Separate domain per locale

Each locale is mapped to its own domain or subdomain:

https://en.mysite.com/about
https://es.mysite.com/about

To configure this, go to Settings → Sitemaps and click Add a Sitemap to create a sitemap for each locale's domain. In the Sitemap Details panel, enter a Name and Reference Name, then click Setup Deployment to attach your domain.

The active locale is stored in a browser cookie. This keeps URLs locale-agnostic but requires client-side logic to read and set the cookie. It is handled entirely in your front-end code and needs no configuration in Agility.

Fetching locale-specific content

When making requests to the Content Fetch API, the locale code is part of the URL path:

GET https://{guid}-api.agilitycms.cloud/{guid}/fetch/{locale}/list/{referenceName}

For example, to fetch a content list in Spanish (Mexico):

GET https://b4cc94dc-api.agilitycms.cloud/b4cc94dc/fetch/es-mx/list/posts

The locale code must match exactly one of the codes configured under Settings → Locales. Requests using an unrecognised locale code will return an error.

Connected Copies

Connected Copies link the same content item across locales, so that each language version is understood to represent the same piece of content.

Shared contentID. Connected copies share the same contentID across all locales. If you have a contentID from a query string or URL parameter, you can use it to retrieve that content in any configured locale.

Language switching. When editing a content item that has connected copies, switching locale using the language dropdown opens the connected copy in the other locale.

Independent content. Editing a connected copy in one locale does not affect the others, unless the field is marked Constant across all languages in the content model. Fields flagged as constant, such as a product SKU or a sort order, are shared across every locale copy: updating the value in one updates it everywhere.