To localise documents in caisy, you must first ensure that you have created multiple locales for your project. You find the main if you go to your project settings and then navigate to Development -> Locales. Important for the usage in the graphql queries is the api identifier of the locale. If you create a new project, you will find that you have a single locale with the api identifier en already created:

The creation of locales is done with the "create" button and following modal. More on that here:

After you created for example a new locale with the api identifier es for Spanish it can look like this on you locales screen:

Notice the fallback locale here. Defining a fallback locale will fill use the default language content for each field of a document, that has no content for the directly queried language.

To use the newly created locale es in our query there is an argument on every single blueprint object and on the all blueprint objects that you can use to define the locale you want to query for.

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

This query above will give you the title of the MainNavigation in Spanish. The language will always effect all the field on the same layer.
Here is 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 the linked documents should be translated and into which language. If you got a larger query with the same locale or you want pass it dynamically something like this would make sense:

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

Here is a javascript example creating normal graphql client (only published documents documents):

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

To get documents in preview mode its very simple, you run the exact same queries, you just apply 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-casiy-preview": true
    },
  })

This example above works with all graphql clients or plain fetch. You just have to apply the http header x-caisy-preview set to true