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

# Localization architecture

> How ButterCMS handles localization with customizable locale names and keys. Content is localized at the item level while maintaining a single schema.

<Info>
  Set up locales in the dashboard first. See [Setting Up Locales](../../create-content/localization/publishing-localized-content).
</Info>

## How localization works in ButterCMS

ButterCMS implements localization at the content level, meaning each piece of content can have multiple locale-specific versions while maintaining the same structure. This architecture provides several key benefits:

### Content-level localization

Unlike some systems that duplicate entire content structures, ButterCMS stores localized content as variants of the same content item. This means:

* **Single content structure**: Your Page Types, Collections, and Components maintain one schema
* **Multiple locale versions**: Each content item can have versions in different locales
* **Independent publishing**: Each locale version can be published independently
* **Shared references**: Reference fields work seamlessly across locales

### Locale configuration

Locales in ButterCMS consist of two parts:

| Component       | Description                           | Example                        |
| --------------- | ------------------------------------- | ------------------------------ |
| **Locale Name** | Human-readable name                   | "English", "Spanish", "French" |
| **API Slug**    | URL-safe identifier used in API calls | `en`, `es`, `fr`               |

### Locale slug guidelines

* Use lowercase and hyphens only
* Prefer ISO language and region codes (e.g. `en`, `en-us`, `es-mx`, `pt-br`)
* Use BCP 47 language tags for consistency with translation tooling
* Slugs are used in all API requests and **cannot be changed after saving** — choose carefully

## Content types and localization

### Pages

Pages support full localization. When localization is enabled:

* Each Page can have content in multiple locales
* The page slug remains the same across locales
* Fields are translated independently per locale
* Publishing status is managed per locale

### Collections

Collections also support localization:

* Collection items can have locale-specific content
* Reference fields automatically respect the requested locale
* The same collection structure is shared across locales

### Blog Posts

Blog Posts support full localization. When localization is enabled:

* Each blog post can have locale variants linked together
* Create translations via the Update endpoint with a `locale` parameter
* Filter posts by locale using the `?locale=` query parameter
* Publishing status is managed per locale

## API request flow

After enabling Localization, you will need to update all API calls to include the locale parameter. The `locale` parameter tells the API which version of the content to return.

```mermaid theme={null}
flowchart LR
    A["Your App<br/>locale=es"] --> B["ButterCMS API<br/>Route to locale"]
    B --> C["Content Store<br/>en | es | fr"]
    B --> D["Return Spanish<br/>Content"]
```

## Single-locale vs multi-locale API formats

ButterCMS supports two API formats for working with localized content:

### Single-locale format (read & write)

Use when working with one locale at a time:

```json theme={null}
{
  "fields": {
    "headline": "Welcome to our site",
    "body": "This is the main content..."
  }
}
```

Query parameter: `?locale=en`

### Multi-locale format (Write API)

Use when creating or updating multiple locales simultaneously:

```json theme={null}
{
  "fields": {
    "en": {
      "headline": "Welcome to our site",
      "body": "This is the main content..."
    },
    "es": {
      "headline": "Bienvenido a nuestro sitio",
      "body": "Este es el contenido principal..."
    }
  }
}
```

The system automatically detects the format based on the structure of the `fields` object.

## Reference field behavior

For reference field behavior across locales, including code examples, see [Locale-Specific Content](./locale-specific-content#managing-different-reference-data-per-locale).

## Default locale behavior

When a locale parameter is omitted from an API request:

1. The API returns content in your organization's **default locale**
2. If content doesn't exist in the requested locale, no automatic fallback occurs
3. You must implement fallback logic in your application if needed

<Tip>
  Design your frontend to handle missing locale content gracefully. Consider implementing a fallback strategy that shows default locale content when translations are unavailable.
</Tip>