Choosing a Localization Strategy

Before you add locales, decide where the boundary between markets sits in your content. In Agility you can localize at three levels, and you can combine them:

1. Field and item level: every market lives in one instance as a locale, and each page and content item has a copy per locale.
2. Page level: markets share an instance, but each market only has the pages it needs, sometimes on its own sitemap and domain.
3. Instance level: each region gets its own instance, with its own content, assets, users and workflow.

This page helps you choose. For the mechanics of URLs and fetching per locale, see the Multi-Locale Guide.

The short version

Strategy	What differs per market	Choose it when	Watch out for
Locales in one instance	Field values. Structure is shared.	Markets share the same site structure and you translate most of it	Adding or removing a component on a page changes that page in every locale
Locale-specific pages and sitemaps	Which pages exist, and optionally the domain	Markets share a content model but not every page	Content lists are shared across the whole instance, so organize content per market yourself
Instance per region	Everything: content, assets, users, workflow	Regional teams need separate permissions, approval or data, or the sites have little in common	Nothing is linked across instances. Shared content needs a deliberate approach such as a content hub

A common path is to start with the first strategy and add the second where a market needs fewer pages. Move to the third when the reason for separating markets is about teams and governance rather than language.

1. Locales in one instance (field and item level)

A locale is a parallel space for your content. When you copy an item into another locale, the two copies stay connected: they share the same contentID, and switching locale while editing opens the counterpart. Each copy has its own field values, and each locale publishes on its own schedule. See Working with Localized Content.

Field-level control comes from the content model. A field marked Constant across all languages keeps one value in every locale, which suits reference codes, sort orders and other values that must never differ by market. Every other field is localized per copy. In the Management API's model JSON, this is the field's copyAcrossAllLanguages setting.

Pages share structure. A page that exists in several locales has the same components in each of them, and its slug can differ per locale. Adding or removing a component on that page applies to every locale it exists in, and deleting a component that was initialized from another locale removes it from all of them. See Multi Locale handling with Sitemaps and Pages.

Choose this when:

• Each market is the same site in a different language or region
• You want one front end, one content model and one editorial team, with translation as a step in the workflow
• You want regional variants of one language (for example en-us and en-ca) that differ in a few details

2. Locale-specific pages and sitemaps (page level)

A page does not appear in a locale until someone initializes it there. So a market can have a smaller site than your primary locale: initialize only the pages that market needs. See Initialize a Page in Another Locale.

An instance can also have several sitemaps. Each sitemap has its own pages, can have its own domain, and uses the same models and components as the others. To give each locale its own domain, create a sitemap per locale domain (see "Separate domain per locale" in the Multi-Locale Guide).

Choose this when:

• Markets share a content model and components, but some markets don't need every page
• Each market has its own domain

Watch out for: content lists belong to the whole instance, not to a sitemap. If some content is only for one market, make that clear with folders and naming, as described in Using Agility for Multiple Sites.

3. Instance per region (instance level)

Separate instances are completely separate in content, assets and editor team, and each can have its own security and workflow. Inside each regional instance you can still use locales for that region's languages. To decide between one instance with several sitemaps and several instances, see Choose Your Tenancy Model.

Choose this when:

• Regional teams must not see or edit each other's content
• Regions need different approval workflows, roles or release schedules
• The regional sites differ in structure, not just in language

Watch out for: connected copies, bulk copy and the Translation API all work between locales inside one instance. They don't link content across instances. If regions share some content, plan for it: see Building a Content Hub and Using Agility for Multiple Sites for the multi-site and multi-instance options.

How content gets into each locale

Whichever strategy you choose, a new locale starts empty. These are the ways to fill it:

Tool	Best for
Save & Localize	One item, while you edit it
Bulk copy to other locales	A selection of items, a page with its content, a whole locale, or a single field
Translate Content (DeepL app)	Translating as part of a copy, or translating fields of an item you are editing
Initialize and Translate APIs	Scripted copies of items, lists and pages, with or without machine translation
Saving with the same contentID	Writing your own translated values from code or a translation service
An AI assistant	Drafting translations for a reviewer to check

See Copying and Translating Content Across Locales, Translating Content with DeepL, Copy and Translate Content Across Locales with the API, Creating Content and Pages in Other Locales and Draft Translations for Another Locale with AI.

Once content is copied, the locales don't update each other. Decide who keeps each locale in step when the source changes.

Sitemaps and URLs per locale

Every Fetch API request names one locale in its path, and that includes the sitemap:

GET https://api.aglty.io/{guid}/fetch/{locale}/sitemap/flat/{channelName}
GET https://api.aglty.io/{guid}/fetch/{locale}/sitemap/nested/{channelName}

The host depends on your instance's region, which is the suffix of its GUID: api.aglty.io for -u, api-ca.aglty.io for -c, api-eu.aglty.io for -e, api-aus.aglty.io for -a and api-usa2.aglty.io for -us2. The @agility/content-fetch SDK picks the right host from the GUID for you.

Because slugs can differ by locale, build each locale's routes from that locale's own sitemap rather than reusing one locale's paths. For a language switcher, find the equivalent page in the other locale's sitemap by pageID (and contentID for dynamic pages), and add hreflang alternates so search engines connect the translations. Multi-Locale Support with Next.js shows both.

How the locale appears in the URL (a path prefix, a domain per locale, or a cookie) is a separate choice, covered in the Multi-Locale Guide.

Fallback to another locale

The Fetch API returns content for the locale you ask for. This documentation doesn't describe any automatic fallback to another locale, so plan as if there is none:

• A component that hasn't been initialized in a locale shows as New on the page and doesn't render on your site.
• If you want missing content to fall back to your default locale, do it in your front end: request the item in the current locale, and if it isn't there, request it in the default locale. The Internationalization training guide shows the pattern.

Decide per content type whether a fallback is acceptable. Showing English inside a French page can be better than a gap for a product spec, and worse for legal text.

Questions to settle before you start

• Is each market a different language, a different region, or a different business?
• Do all markets need every page?
• Do regional teams need to be kept apart, or do they work together?
• Which fields must never differ between markets?
• Who translates, who reviews, and who keeps locales in step after launch?
• What should a visitor see when a translation is missing?

Plan your locales before you create them: you can disable a locale yourself at any time, but permanently deleting one has to be done by the Agility support team. See Locales.