# Choosing a Localization Strategy

> Source: https://agilitycms.com/docs/developers/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](https://agilitycms.com/docs/developers/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](https://agilitycms.com/docs/editors/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](https://agilitycms.com/docs/editors/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](https://agilitycms.com/docs/editors/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](https://agilitycms.com/docs/developers/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](https://agilitycms.com/docs/overview/using-agility-cms-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](https://agilitycms.com/docs/developers/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](https://agilitycms.com/docs/overview/building-a-content-hub) and [Using Agility for Multiple Sites](https://agilitycms.com/docs/overview/using-agility-cms-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](https://agilitycms.com/docs/editors/copying-and-translating-content), [Translating Content with DeepL](https://agilitycms.com/docs/editors/translating-content-with-deepl), [Copy and Translate Content Across Locales with the API](https://agilitycms.com/docs/developers/copy-and-translate-content-with-the-api), [Creating Content and Pages in Other Locales](https://agilitycms.com/docs/developers/creating-content-and-pages-in-other-locales) and [Draft Translations for Another Locale with AI](https://agilitycms.com/docs/editors/ai-recipe-translate-content).

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](https://agilitycms.com/docs/nextjs/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](https://agilitycms.com/docs/developers/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](https://agilitycms.com/docs/training-guide/developer-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](https://agilitycms.com/docs/editors/locales).