Skip to main content
Set up locales in the dashboard first. See Setting Up Locales.

​
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:
ComponentDescriptionExample
Locale NameHuman-readable name”English”, “Spanish”, “French”
API SlugURL-safe identifier used in API callsen, 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

The built-in Blog Engine has a different localization approach:
  • Blog posts use tags for locale identification (e.g., en, es, jp)
  • Filter posts by tag to retrieve locale-specific content
  • Alternative: Migrate to custom Page Types for full localization support

​
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.

​
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: 
{
  "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: 
{
  "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.

​
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
Design your frontend to handle missing locale content gracefully. Consider implementing a fallback strategy that shows default locale content when translations are unavailable.