Concepts

Locales

Use locales for multilingual and regional content.

Prismic supports creating localized versions of your content for different languages and regions. Each locale uses a code like en-us or fr-ca to represent a specific language and region combination.

Content writers can copy documents between locales or write individual documents for each.

A screenshot of a document's Locales selector in the top-right corner
of the Page Builder.

A document’s Locales selector in the top-right corner of the Page Builder.

You can use locales for:

  • Translating content (en-us and es-mx for English and Spanish content)
  • Localizing content (en-gb and en-us for British vs American English)
  • Both translating and localizing (en-ca and fr-ca for English and French Canadian audiences)

Fetch content from locales

Use the Prismic client’s lang query parameter to fetch from a specific locale:

// Fetches all blog posts from the `en-ca` locale.
const blogPosts = await client.getAllByType("blog_post", {
  lang: "en-ca",
});

Use the * wildcard to fetch content from all locales:

// Fetches all blog posts from all locales.
const page = await client.getAllByType("blog_post", {
  lang: "*",
});

By default, documents are fetched from your repository’s master locale:

const client = createClient("example-prismic-repo");

// Fetches all blog posts from the master locale.
const blogPosts = await client.getAllByType("blog_post");

Learn more about the lang query parameter

Add locales to routes

You can add locales to page URLs by configuring your website’s route resolvers.

The following example route resolver adds a page’s locale to the start of its URL via the :lang keyword. The :lang keyword is replaced with the document’s locale.

{
  "type": "page",
  "path": "/:lang/:uid"
}

The above route resolver may output a URL like /en-ca/my-first-post.

The :lang? keyword (with a ?) omits the locale if the page is from the master locale.

{
  "type": "page",
  "path": "/:lang?/:uid"
}

If en-ca is the master locale, the previous /en-ca/my-first-post example URL would be /my-first-post instead.

Learn more about routes

Locales in the API

The Document API provides a document’s locale in its lang property:

{
  "id": "YCiUyRUAACQAxfZK",
  "uid": "my-first-post",
  "url": "/blog/my-first-post",
  "type": "blog_post",
  "href": "https://example-prismic-repo.cdn.prismic.io/api/v2/...",
  "tags": ["Tag 1", "Tag 2"],
  "first_publication_date": "2021-02-14T03:22:26+0000",
  "last_publication_date": "2022-07-09T00:36:18+0000",
  "slugs": ["my-first-post"],
  "linked_documents": [],
  "lang": "fr-fr",
  "alternate_languages": [],
  "data": {
    // ...
  }
}

A document’s translated versions are listed in the document’s alternate_languages property.

{
  "id": "YCiUyRUAACQAxfZK",
  "uid": "my-first-post",
  // ...
  "alternate_languages": [
    {
      "id": "XTb4mBAAACQAOfrg",
      "type": "homepage",
      "lang": "fr-fr"
    }
  ],
  "data": {
    // ...
  }
}

How to manage locales

Locales are managed in your Prismic repository’s settings.

Add a locale

  • Open your language settings

    Navigate to your Prismic repository and go to Settings > Translations & Locales.

    A screenshot of the Translations & Locales settings in a Prismic
repository.

    The Translations & Locales settings in a Prismic repository.

  • Add a locale

    In the Add new locales to this repository section, select a locale from the dropdown.

    A screenshot of the dropdown of available locales.

    The dropdown of available locales.

    If your locale is not in the list, add a custom locale by selecting Add custom locale in the dropdown.

    Click Add locale after selecting a locale.

Set the master locale

  • Open your language settings

    Navigate to your Prismic repository and go to Settings > Translations & Locales.

    A screenshot of the Translations & Locales settings in a Prismic
repository.

    The Translations & Locales settings in a Prismic repository.

  • Select a master locale

    In the Manage your locales section, click the Set as master button for your new master locale.

    A screenshot of the Set as master button in the list of
locales.

    The Set as master button in the list of locales.

    Your selected locale will be the new default locale in the Page Builder and the Document API.

Remove a locale

  • Delete all documents in the locale

    All documents in a locale must be deleted before deleting the locale.

  • Open your language settings

    Navigate to your Prismic repository and go to Settings > Translations & Locales.

    A screenshot of the Translations & Locales settings in a Prismic
repository.

    The Translations & Locales settings in a Prismic repository.

  • Delete a locale

    In the Manage your locales section, click the trash can button for the locale to be deleted.

    A screenshot of the trash can button in the list of
locales.

    The trash can button in the list of locales.