To localize documents in caisy, you must first make sure that you have created multiple locales for your project. You can find the main settings by going to your project settings, then navigating to Development -> Locales. It's important to note the API identifier of the locale for use in GraphQL queries. If you create a new project, you'll find that a single locale with the API identifier en has already been created:

The creation of locales is accomplished using the "Create" button and the accompanying modal. You can find more information on this process here:

After you create a new locale with the API identifier es for Spanish, for example, it should look like this on your locales screen:

Note the fallback locale in this example. Defining a fallback locale will use the default language content for each field of a document that does not have content for the directly queried language

To use the newly created locale es in your query, you can add an argument to each blueprint object and the all blueprint objects to define the desired locale for the query.

{
  MainNavigation(locale: "es"){
    title
  }
}

This query will return the title of the MainNavigation in Spanish. The selected language will always affect all fields in the same layer. Here's an example of a nested query:

{
  MainNavigation(locale: "es"){
    title
    links(locale: "es"){
      ... on Page {
        title 
        slug
        id
      }
    }
  }
}

With this approach, you can determine for each level whether linked documents should be translated and into which language. If you have a larger query with the same locale or want to pass it dynamically, something like the following could be useful:

query MainNavigation($locale: String) {
  MainNavigation(locale: $locale) {
    title
    links(locale: $locale) {
      ... on Page {
        title
        slug
        id
      }
    }
  }
}

Here's a JavaScript example creating a normal GraphQL client (only for published documents):

  const graphQLClient = new GraphQLClient(process.env.CAISY_GQL_ENDPOINT, {
    headers: {
      "x-caisy-apikey": process.env.CAISY_API_KEY,
    },
  })

To retrieve documents in preview mode, it's very simple. You run the same queries, but add an extra HTTP header x-caisy-preview:true.

  const graphQLClient = new GraphQLClient(process.env.CAISY_GQL_ENDPOINT, {
    headers: {
      "x-caisy-apikey": process.env.CAISY_API_KEY,
      "x-caisy-preview": true
    },
  })

This example works with all GraphQL clients or plain fetch, you just need to add the HTTP header x-caisy-preview to true.