Localization

Graph stores each entry's field values in the base locale, en-US, and lets editors add translations of its text fields in the other languages your workspace enables. Any request can ask for a locale, and gets those translations back in place of the original text.

Requesting a locale

Add locale to any REST request:

curl "https://api.graphcms.io/v1/content/blog-posts/hello-world?locale=fr-FR" \
  -H "Authorization: Bearer $GRAPH_API_KEY"

{
  "success": true,
  "data": {
    "slug": "hello-world",
    "locale": "fr-FR",
    "fields": {
      "excerpt": "Notre premier article.",
      "body": "<p>Welcome to the blog.</p>",
      "featured": true
    }
  }
}

Or pass it as an argument in GraphQL, on contentEntries, contentEntry and contentEntryById:

1query {
2  contentEntry(contentType: "blog-posts", slug: "hello-world", locale: "fr-FR") {
3    locale
4    fields
5  }
6}

The SDK takes it as an option: graph.content.entry('blog-posts', 'hello-world', { locale: 'fr-FR' }).

How translations resolve

• Only text and textarea fields are translated. Every other field type (html, number, media and so on) always returns its original value.
• A text field with no translation in the requested locale returns the original, en-US text. You never get an empty field because a translation is missing.
• Without locale, or with locale=en-US, you get the original values.
• The response's locale property says which locale was applied.

In the example above, excerpt (a textarea) is translated, body (an html field) is not, and featured (a boolean) is not translatable.

Supported locales

Codes are case-sensitive. Anything else is rejected: 400 over REST with Unsupported locale "fr". Use a code like en-US or fr-FR., and a BAD_USER_INPUT error over GraphQL. A supported code your workspace hasn't enabled simply has no translations, so it returns the original text.

Which languages editors can translate into is set in the dashboard under Settings → Localization.

Locale versus language

Entries also have a language, and the API accepts a language parameter. They do different things:

• locale chooses which translation of an entry's text fields to return. It never changes which entries you get.
• language filters entries by the language they were written in. On REST it defaults to en-US.

For a site that shows the same entries in several languages, use locale. See Querying.

A multilingual site

1const API_URL = 'https://api.graphcms.io/v1';
2
3export async function getPost(slug, locale = 'en-US') {
4  const params = new URLSearchParams({ locale });
5  const response = await fetch(`${API_URL}/content/blog-posts/${slug}?${params}`, {
6    headers: { Authorization: `Bearer ${process.env.GRAPH_API_KEY}` },
7  });
8  if (response.status === 404) return null;
9  const { data } = await response.json();
10  return data;
11}
12
13// /fr/blog/hello-world
14const post = await getPost('hello-world', 'fr-FR');