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.
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"
// 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)
})
$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();
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"
}})
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();
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);
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()
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)
{
"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": []
}