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

# Locale-specific content

> Learn how to create content that only exists in specific locales, manage regional variations, and handle content that shouldn't be translated.

# Locale-specific content

Not all content needs to exist in every locale. ButterCMS supports creating content that is unique to specific markets, regions, or languages without requiring equivalent content in other locales.

## Understanding locale-specific content

Locale-specific content differs from translated content in important ways:

| Aspect    | Translated Content               | Locale-Specific Content           |
| --------- | -------------------------------- | --------------------------------- |
| Purpose   | Same message, different language | Different message per region      |
| Structure | Same fields, different values    | May have unique content items     |
| Workflow  | Translate from source            | Create independently              |
| Examples  | Product descriptions, blog posts | Regional promotions, local events |

## Creating locale-specific Pages

When localization is enabled, each page can have independent content for each locale. The pages created in other languages will remain empty until you enter content specifically for that locale.

![Locale selector for pages](https://cdn.buttercms.com/lBCuFyLiSDOjhvTUHMp7)

### Creating content for one locale only

To create content that exists only in a specific locale:

1. Navigate to your Page Type or create a new page
2. Select the target locale from the locale dropdown
3. Add your content for that locale only
4. Publish the page

The page will only be available when the API is called with that specific locale parameter.

### Example: regional promotion

```javascript theme={null}
// This page only exists in the German locale
const germanPromo = await butter.page.retrieve(
  'promotional_pages',
  'oktoberfest-sale',
  { locale: 'de' }
);

// Calling with English locale would return no content
const englishPromo = await butter.page.retrieve(
  'promotional_pages',
  'oktoberfest-sale',
  { locale: 'en' }
); // Returns empty or error
```

## Locale-specific Collection items

Collections also support locale-specific content. All the fields in your Default Locale will be defined and the same fields are created for other Locales automatically. However, the content you create for your default locale in a Collection will not automatically appear in your other localized Collections.

### Use cases for locale-specific Collection items

**Regional Team Members**

```javascript theme={null}
// Team members collection with region-specific entries
// Some team members only appear for certain markets
const usTeam = await butter.content.retrieve(['team_members'], {
  locale: 'en-us'
});

const ukTeam = await butter.content.retrieve(['team_members'], {
  locale: 'en-gb'
});
// UK team may include different members
```

**Local Store Locations**

```javascript theme={null}
// Store locations that only exist in certain regions
const germanStores = await butter.content.retrieve(['store_locations'], {
  locale: 'de'
});
```

**Region-Specific FAQs**

```javascript theme={null}
// FAQs that address local regulations or customs
const euFaqs = await butter.content.retrieve(['faqs'], {
  locale: 'de',
  'fields.category': 'gdpr'
});
```

## Managing different Reference field data per locale

Reference fields work seamlessly with localization, allowing different reference relationships for different language versions. This enables:

* Locale-specific content recommendations
* Region-appropriate product references
* Language-specific related content

### Example: locale-specific references

Imagine a product page that references related products. In different markets, you might want to show different related items:

**US Market (en-us)**

* Related product: "Summer Collection"
* Shipping info: US shipping details

**German Market (de)**

* Related product: "Herbstkollektion" (Autumn Collection)
* Shipping info: EU shipping details

```javascript theme={null}
// The same page, different references per locale
const usProductPage = await butter.page.retrieve('product', 'main-product', {
  locale: 'en-us',
  levels: 2  // Include referenced content
});

const deProductPage = await butter.page.retrieve('product', 'main-product', {
  locale: 'de',
  levels: 2
});
// References are resolved based on the locale
```

## Content strategy patterns

### Pattern 1: mirror structure (recommended for most cases)

All locales have the same pages, but with translated or adapted content.

```
/about-us     → en, de, fr, es (all locales)
/products     → en, de, fr, es (all locales)
/contact      → en, de, fr, es (all locales)
```

**Best for**: Corporate sites, e-commerce, documentation

### Pattern 2: adaptive structure

Some pages exist only in certain locales based on market needs.

```
/about-us     → en, de, fr, es (all locales)
/oktoberfest  → de only
/4th-of-july  → en-us only
/bastille-day → fr only
```

**Best for**: Marketing sites, regional promotions, local events

### Pattern 3: hybrid structure

Core content mirrored, with locale-specific additions.

```
/core-product → en, de, fr, es (all locales)
/us-only-service → en-us only
/eu-gdpr-info → de, fr (EU locales only)
```

**Best for**: SaaS products, services with regional variations

## Handling missing locale content

For strategies and code examples for handling missing locale content, see [Fetching Localized Content](./fetching-localized-content-api#handling-missing-locale-content).

## Best practices

### Planning locale-specific content

1. **Document your content strategy**: Define which content types will be mirrored vs. locale-specific
2. **Use consistent naming**: Even locale-specific content should follow naming conventions
3. **Consider SEO implications**: Locale-specific pages need proper hreflang tags

### Content organization

* **Use tags or categories** to identify locale-specific content
* **Create a content matrix** showing which pages exist in which locales
* **Establish review workflows** for locale-specific content approval

### Technical implementation

* **Use the `preview` parameter** to check locale content before publishing
* **Implement locale detection** to route users appropriately

<Warning>
  Remember that content created in only one locale won't appear when the API is called with a different locale parameter. Ensure your frontend handles this scenario.
</Warning>