1. Field-level Translation

Field-level Translation

It is possible to use filter queries with stories translated using Storyblok's Field-level Translation. The field key must be extended with __i18n__ and a language code configured in the space settings. The following syntax applies:

stories/?filter_query[field__i18n__language_code][operation]=value

The following criteria must be fulfilled to successfully use filter queries with translated stories:

  • The space must be configured to publish languages independently.
  • The space must be configured to have use_filter_query_in_translated_stories enabled.
  • The request must contain the language parameter specifying the target language. Please refer to the Internationalization developer guide for further information.
  • The request must contain version=published.

For spaces created before February 6th, 2024, please contact Storyblok's support team to enable the internal use_filter_query_in_translated_stories option. For spaces created after February 6th, 2024, this option is enabled by default.

Examples Use Cases

  • filter_query[headline__i18n__de][like]=Die Symphonie der Erde*

    Returns all stories whose headline starts with the words "Die Symphonie der Erde" and are published in German, represented by the language code de

  • filter_query[headline__i18n__es_co][like]=Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul

    Returns all stories with this exact headline that are published in Spanish (Colombia), represented by the language code es-co

    Please note that the language code needs to be formatted with an underscore in the filter_query (es_co), even if it is defined with a hyphen in the space settings (es-co).

  • Example Request and Response

    The following example demonstrates how to use the filter_query parameter with nestable bloks.

    Request
    curl "https://api.storyblok.com/v2/cdn/stories/?filter_query[headline__i18n__es_co][in]=Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul&version=published&language=es-co" \
      -X GET \
      -H "Accept: application/json" \
      -H "Content-Type: application/json"
    Request
    // Using the Universal JavaScript Client:
    // https://github.com/storyblok/storyblok-js-client
    Storyblok.get('cdn/stories/', {
      "filter_query": {
        "headline__i18n__es_co": {
          "in": "Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul"
        }
      },
      "version": "published",
      "language": "es-co"
    })
      .then(response => {
        console.log(response)
      }).catch(error => { 
        console.log(error)
      })
    Request
    $client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');
    
    $client->getStories([
      "filter_query" =>  [
        "headline__i18n__es_co" =>  [
          "in" =>  "Sinfonía de la Tierra =>  Navegar por las maravillas y los desafíos de nuestro oasis azul"
        ]
      ],
      "version" =>  "published",
      "language" =>  "es-co"
    ])->getBody();
    Request
    require 'storyblok'
    client = Storyblok::Client.new(oauth_token: 'YOUR_OAUTH_TOKEN')
    
    client.stories({:params => {
      "filter_query" =>  {
        "headline__i18n__es_co" =>  {
          "in" =>  "Sinfonía de la Tierra =>  Navegar por las maravillas y los desafíos de nuestro oasis azul"
        }
      },
      "version" =>  "published",
      "language" =>  "es-co"
    }})
    Request
    HttpResponse<String> response = Unirest.get("https://api.storyblok.com/v2/cdn/stories/?filter_query[headline__i18n__es_co][in]=Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul&version=published&language=es-co")
      .asString();
    Request
    var client = new RestClient("https://api.storyblok.com/v2/cdn/stories/?filter_query[headline__i18n__es_co][in]=Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul&version=published&language=es-co");
    var request = new RestRequest(Method.GET);
    
    IRestResponse response = client.Execute(request);
    Request
    import Foundation
    
    let request = NSMutableURLRequest(url: NSURL(string: "https://api.storyblok.com/v2/cdn/stories/?filter_query[headline__i18n__es_co][in]=Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul&version=published&language=es-co")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
    request.method = "GET"
    
    let session = URLSession.shared
    let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
      if (error != nil) {
        print(error)
      } else {
        let httpResponse = response as? HTTPURLResponse
        print(httpResponse)
      }
    })
    
    dataTask.resume()
    Request
    import requests
    
    url = "https://api.storyblok.com/v2/cdn/stories/"
    
    querystring = {"filter_query":{"headline__i18n__es_co":{"in":"Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul"}},"version":"published","language":"es-co"}
    
    payload = ""
    headers = {}
    
    response = requests.request("GET", url, data=payload, headers=headers, params=querystring)
    
    print(response.text)
    Response
    {
      "stories": [
        {
          "name": "Earth's Symphony: Navigating the Wonders and Challenges of Our Blue Oasis",
          "created_at": "2024-02-16T14:22:09.108Z",
          "published_at": "2024-03-12T13:15:31.325Z",
          "id": 444996765,
          "uuid": "660452d2-1a68-4493-b5b6-2f03b6fa722b",
          "content": {
            "_uid": "6bdf037c-f713-415c-a26a-8a9cfc926c85",
            "image": {
              "id": 14114772,
              "alt": "",
              "name": "",
              "focus": "",
              "title": "",
              "source": "",
              "filename": "https://a.storyblok.com/f/276232/2560x1946/ee938cf736/earth.jpg",
              "copyright": "",
              "fieldtype": "asset",
              "meta_data": {},
              "is_private": "",
              "is_external_url": false
            },
            "author": "51eed33d-855f-415c-ac0d-4404e03b89e1",
            "topics": ["solar-system"],
            "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
            "headline": "Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul",
            "component": "article",
            "scheduled": "2023-10-01 15:00",
            "categories": ["45d968b6-5790-4fbb-aa41-5781b8edde51", "d8e48716-0ecf-4059-b568-343bf54e4128"],
            "highlighted": false
          },
          "slug": "earths-symphony-navigating-wonders-challenges-blue-oasis",
          "full_slug": "es-co/articles/earths-symphony-navigating-wonders-challenges-blue-oasis",
          "sort_by_date": null,
          "position": 0,
          "tag_list": [],
          "is_startpage": false,
          "parent_id": 444991588,
          "meta_data": null,
          "group_id": "8d99d18d-5c97-42cd-a646-51e0c553f26a",
          "first_published_at": "2024-02-16T14:30:11.990Z",
          "release_id": null,
          "lang": "es-co",
          "path": null,
          "alternates": [],
          "default_full_slug": null,
          "translated_slugs": null
        }
      ],
      "cv": 1710249331,
      "rels": [],
      "links": []
    }