Locales

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.

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");

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.

Locales in the API

The Content 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.

  

• Add a locale

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

  

  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.

  

• Select a master locale

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

  

  Your selected locale will be the new default locale in the Page Builder and the Content 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.

  

• Delete a locale

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