Skip navigation

Get localized content items

4 min read
Download PDF

Localization in Kontent.ai allows you to define multiple languages for your project and create localized culture-specific content. Let's look at how you can retrieve localized content from your project.

Table of contents

    Choose a URL pattern

    When developing multilingual web apps, it is a good practice to ensure unique URL addresses for each page.

    1. Language prefixes

    One approach is to use language prefixes in URLs, such as en-us or es-es, to differentiate between content cultures.

    For instance, the URLs can be https://myapp.com/en-us/about-usfor English language and https://myapp.com/es-es/about-us for Spanish language. In this scenario, you get content items in a specific language.

    2. Localized URL slugs

    Another way is to combine the language prefixes with localized names of your content items. That is using localized URL slugs.

    For example, a URL slug of the About us content item in English is about-us. Translated to Spanish, the URL slug changes to, for example, acerda-de-nosotros. The URL for the About us content item in Spanish becomes https://myapp.com/es-es/acerda-de-nosotros. In this case, you need to get content items by their URL slug value.

    If you're thinking through your URL patterns, make sure to check considerations for multilingual URLs.

    Languages and localization

    Each language in your Kontent.ai project is uniquely identified by its codename. This codename can be any string you choose, such as, Englishen-US, or en-GB.

    Your project's default language

    Every project comes with a single default language that cannot be removed. When you request content without specifying a language, the Delivery API returns content in the default language.

    Get localized content items

    To get localized content, specify the language parameter and provide the codename of the requested language. For example, to get an article named About Us article in the Spanish language, specify the item's codename and the language's codename.

    • GraphQL
    query GetArticleInSpanish { article(codename: "about_us", languageFilter: {languageCodename: "es-ES"}) { title } }
    query GetArticleInSpanish { article(codename: "about_us", languageFilter: {languageCodename: "es-ES"}) { title } }
    • Java
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java import kontent.ai.delivery.*; // Initializes a DeliveryClient DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>"); // Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models // Registers the model class for articles client.registerType(Article.class); // Gets the Spanish variant of an article CompletionStage<Article> item = client.getItem( "about_us", Article.class, DeliveryParameterBuilder.params() .language("es-ES") .build() );
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java import kontent.ai.delivery.*; // Initializes a DeliveryClient DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>"); // Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models // Registers the model class for articles client.registerType(Article.class); // Gets the Spanish variant of an article CompletionStage<Article> item = client.getItem( "about_us", Article.class, DeliveryParameterBuilder.params() .language("es-ES") .build() );
    • JavaScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7' }); const response = await deliveryClient.item('about_us') .languageParameter('es-ES') .toPromise();
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7' }); const response = await deliveryClient.item('about_us') .languageParameter('es-ES') .toPromise();
    • C#
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Delivery; // Creates an instance of the delivery client // ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client IDeliveryClient client = DeliveryClientBuilder .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7") .Build(); // Gets an article in Spanish // Create strongly typed models according to https://kontent.ai/learn/net-strong-types IDeliveryItemResponse<Article> response = await client.GetItemAsync<Article>("about_us", new LanguageParameter("es-ES") ); Article item = response.Item;
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Delivery; // Creates an instance of the delivery client // ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client IDeliveryClient client = DeliveryClientBuilder .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7") .Build(); // Gets an article in Spanish // Create strongly typed models according to https://kontent.ai/learn/net-strong-types IDeliveryItemResponse<Article> response = await client.GetItemAsync<Article>("about_us", new LanguageParameter("es-ES") ); Article item = response.Item;
    • PHP
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php // Defined by Composer to include required libraries require __DIR__ . '/vendor/autoload.php'; use Kontent\Ai\Delivery\DeliveryClient; $client = new DeliveryClient('8d20758c-d74c-4f59-ae04-ee928c0816b7'); $items = $client->getItem('about_us', (new QueryParams()) ->language('es-ES'));
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php // Defined by Composer to include required libraries require __DIR__ . '/vendor/autoload.php'; use Kontent\Ai\Delivery\DeliveryClient; $client = new DeliveryClient('8d20758c-d74c-4f59-ae04-ee928c0816b7'); $items = $client->getItem('about_us', (new QueryParams()) ->language('es-ES'));
    • cURL
    curl --request GET \ --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items/about_us?language=es-ES' \ --header 'content-type: application/json'
    curl --request GET \ --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items/about_us?language=es-ES' \ --header 'content-type: application/json'
    • Ruby
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby require 'delivery-sdk-ruby' delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '8d20758c-d74c-4f59-ae04-ee928c0816b7' delivery_client.item('about_us') .language('es-ES') .execute do |response| item = response.item end
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby require 'delivery-sdk-ruby' delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '8d20758c-d74c-4f59-ae04-ee928c0816b7' delivery_client.item('about_us') .language('es-ES') .execute do |response| item = response.item end
    • TypeScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { createDeliveryClient } from '@kontent-ai/delivery-sdk'; import { Article } from './models/Article'; const deliveryClient = createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7', }); const response = await deliveryClient.item<Article>('about_us') .languageParameter('es-ES') .toPromise();
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { createDeliveryClient } from '@kontent-ai/delivery-sdk'; import { Article } from './models/Article'; const deliveryClient = createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7', }); const response = await deliveryClient.item<Article>('about_us') .languageParameter('es-ES') .toPromise();

    If the content item doesn't exist in the specified language, the Delivery API checks if the content exists in the fallback language configured for the requested language.

    Get items by localized URL slug

    Depending on how you implement routing in your app, you might want to request content items based on the knowledge of their URL slugs.

    To retrieve a content item by a localized URL slug, you need to specify the language parameter and then filter by URL slug value. If you omit the language parameter, you get content in the default language.

    For example, to get an About us content item whose URL slug in Spanish is acerda-de-nosotros, you need to specify the following:

    • The language's codename using the language parameter. For Spanish it's es-ES.
    • The content item's URL slug value using the equals filter.
    • GraphQL
    query GetArticlesByLocalizedSlug { article_All(where: {title: {eq: "acerda-de-nosotros"}}, languageFilter: {languageCodename: "es-ES"}) { items { title } } }
    query GetArticlesByLocalizedSlug { article_All(where: {title: {eq: "acerda-de-nosotros"}}, languageFilter: {languageCodename: "es-ES"}) { items { title } } }
    • Java
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java import kontent.ai.delivery.*; // Initializes a DeliveryClient DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>"); // Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models // Registers the model class for articles client.registerType(Article.class); // Gets the Spanish variant of an "About us" content item that has "acerda-de-nosotros" in its "URL pattern" element CompletionStage<List<Article>> items = client.getItems( Article.class, DeliveryParameterBuilder.params() .language("es-ES") .filterEquals("system.type", "article") .filterEquals("elements.url_pattern", "acerda-de-nosotros") .build(); );
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java import kontent.ai.delivery.*; // Initializes a DeliveryClient DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>"); // Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models // Registers the model class for articles client.registerType(Article.class); // Gets the Spanish variant of an "About us" content item that has "acerda-de-nosotros" in its "URL pattern" element CompletionStage<List<Article>> items = client.getItems( Article.class, DeliveryParameterBuilder.params() .language("es-ES") .filterEquals("system.type", "article") .filterEquals("elements.url_pattern", "acerda-de-nosotros") .build(); );
    • JavaScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7' }); const response = await deliveryClient.items('article') .type('article') .languageParameter('es-ES') .depthParameter(0) .equalsFilter('elements.url_pattern', 'acerda-de-nosotros') .toPromise();
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7' }); const response = await deliveryClient.items('article') .type('article') .languageParameter('es-ES') .depthParameter(0) .equalsFilter('elements.url_pattern', 'acerda-de-nosotros') .toPromise();
    • C#
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Delivery; // Creates an instance of the delivery client // ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client IDeliveryClient client = DeliveryClientBuilder .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7") .Build(); // Gets the 'About us' content item in Spanish based on the item's URL slug value // Create strongly typed models according to https://kontent.ai/learn/net-strong-types IDeliveryItemListingResponse<Article> response = await client.GetItemsAsync<Article>( new LanguageParameter("es-ES"), new EqualsFilter("system.type", "article"), new EqualsFilter("elements.url_pattern", "acerda-de-nosotros") ); IList<Article> items = response.Items;
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Delivery; // Creates an instance of the delivery client // ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client IDeliveryClient client = DeliveryClientBuilder .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7") .Build(); // Gets the 'About us' content item in Spanish based on the item's URL slug value // Create strongly typed models according to https://kontent.ai/learn/net-strong-types IDeliveryItemListingResponse<Article> response = await client.GetItemsAsync<Article>( new LanguageParameter("es-ES"), new EqualsFilter("system.type", "article"), new EqualsFilter("elements.url_pattern", "acerda-de-nosotros") ); IList<Article> items = response.Items;
    • PHP
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php // Defined by Composer to include required libraries require __DIR__ . '/vendor/autoload.php'; use Kontent\Ai\Delivery\DeliveryClient; $client = new DeliveryClient('8d20758c-d74c-4f59-ae04-ee928c0816b7'); $items = $client->getItems((new QueryParams()) ->language('es-ES') ->equals('system.type', 'article') ->equals('elements.url_pattern', 'acerda-de-nosotros'));
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php // Defined by Composer to include required libraries require __DIR__ . '/vendor/autoload.php'; use Kontent\Ai\Delivery\DeliveryClient; $client = new DeliveryClient('8d20758c-d74c-4f59-ae04-ee928c0816b7'); $items = $client->getItems((new QueryParams()) ->language('es-ES') ->equals('system.type', 'article') ->equals('elements.url_pattern', 'acerda-de-nosotros'));
    • cURL
    curl --request GET \ --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items?language=es-ES&system.type=article&elements.url_pattern=acerda-de-nosotros' \ --header 'content-type: application/json'
    curl --request GET \ --url 'https://deliver.kontent.ai/8d20758c-d74c-4f59-ae04-ee928c0816b7/items?language=es-ES&system.type=article&elements.url_pattern=acerda-de-nosotros' \ --header 'content-type: application/json'
    • Ruby
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby require 'delivery-sdk-ruby' delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '8d20758c-d74c-4f59-ae04-ee928c0816b7' delivery_client.items([ 'system.type'.eq('article'), 'elements.url_pattern'.eq('acerda-de-nosotros') ]) .language('es-ES') .execute do |response| items = response.items end
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby require 'delivery-sdk-ruby' delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '8d20758c-d74c-4f59-ae04-ee928c0816b7' delivery_client.items([ 'system.type'.eq('article'), 'elements.url_pattern'.eq('acerda-de-nosotros') ]) .language('es-ES') .execute do |response| items = response.items end
    • TypeScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { createDeliveryClient } from '@kontent-ai/delivery-sdk'; import { Article } from './models/Article'; const deliveryClient = createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7', }); const response = await deliveryClient.items<Article>() .type('article') .languageParameter('es-ES') .depthParameter(0) .equalsFilter('elements.url_pattern', 'acerda-de-nosotros') .toPromise();
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { createDeliveryClient } from '@kontent-ai/delivery-sdk'; import { Article } from './models/Article'; const deliveryClient = createDeliveryClient({ environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7', }); const response = await deliveryClient.items<Article>() .type('article') .languageParameter('es-ES') .depthParameter(0) .equalsFilter('elements.url_pattern', 'acerda-de-nosotros') .toPromise();

    If the specified query doesn't match any content items, the Delivery API returns an empty response.

    Ignoring language fallbacks

    To ignore language fallbacks and retrieve content items only in the specified language, you need to filter out any content items whose language is different from the specified language.

    The following table shows what content the Delivery API returns for specific combinations of language-related filters. The example works with a Kontent.ai project with the default language set as English en-US and the second language set as Spanish es-ES, which falls back to the default language.

    • language=es-ES – Specifies the codename of the requested language.
    • system.language=es-ES – Filters content items by their language.
    language parameter valuesystem.language parameter valueBehavior
    es-ES<not set>The API returns content items in Spanish. If an item is not translated to Spanish, the API returns the English (en-us) version of the items as fallback.
    es-ESes-ESThe API returns only content items in Spanish. If an item is not translated to Spanish, the API doesn't return it.
    es-ESen-USThe API returns only content items in English provided they don't have content in Spanish. If an item is translated to Spanish, it is not returned.

    For example, this is how you retrieve content items translated to Spanish language without any fallbacks.

    • GraphQL
    query GetArticlesInSpanishOnly { article_All( # Requests items in Spanish languageFilter: {languageCodename: "es-ES"}, # Filters the items so that only Spanish is returned, ignoring language fallbacks where: {_system_: {language: {_system_: {codename: {eq: "es-ES"}}}}}) { items { title } } }
    query GetArticlesInSpanishOnly { article_All( # Requests items in Spanish languageFilter: {languageCodename: "es-ES"}, # Filters the items so that only Spanish is returned, ignoring language fallbacks where: {_system_: {language: {_system_: {codename: {eq: "es-ES"}}}}}) { items { title } } }
    • Java
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java import kontent.ai.delivery.*; // Initializes a DeliveryClient DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>"); // Gets the Spanish variant of all content items (while ignoring language fallbacks) CompletionsStage<ContentItemsListingResponse> listingResponse = client.getItems( DeliveryParameterBuilder.params() .language("es-ES") .filterEquals("system.language", "es-ES") .build() );
    // Tip: Find more about Java SDK at https://kontent.ai/learn/java import kontent.ai.delivery.*; // Initializes a DeliveryClient DeliveryClient client = new DeliveryClient("<YOUR_PROJECT_ID>"); // Gets the Spanish variant of all content items (while ignoring language fallbacks) CompletionsStage<ContentItemsListingResponse> listingResponse = client.getItems( DeliveryParameterBuilder.params() .language("es-ES") .filterEquals("system.language", "es-ES") .build() );
    • JavaScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '975bf280-fd91-488c-994c-2f04416e5ee3', }); const response = await deliveryClient.items() .languageParameter('es-ES') .equalsFilter('system.language', 'es-ES') .toPromise();
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript const KontentDelivery = require('@kontent-ai/delivery-sdk'); const deliveryClient = KontentDelivery.createDeliveryClient({ environmentId: '975bf280-fd91-488c-994c-2f04416e5ee3', }); const response = await deliveryClient.items() .languageParameter('es-ES') .equalsFilter('system.language', 'es-ES') .toPromise();
    • C#
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Delivery; // Creates an instance of the delivery client // ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client IDeliveryClient client = DeliveryClientBuilder .WithProjectId("975bf280-fd91-488c-994c-2f04416e5ee3") .Build(); // Gets the Spanish variant of all content items and ignores language fallbacks IDeliveryItemListingResponse<object> response = await client.GetItemsAsync<object>( new LanguageParameter("es-ES"), new EqualsFilter("system.language", "es-ES") ); IList<object> items = response.Items;
    // Tip: Find more about .NET SDKs at https://kontent.ai/learn/net using Kontent.Ai.Delivery; // Creates an instance of the delivery client // ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client IDeliveryClient client = DeliveryClientBuilder .WithProjectId("975bf280-fd91-488c-994c-2f04416e5ee3") .Build(); // Gets the Spanish variant of all content items and ignores language fallbacks IDeliveryItemListingResponse<object> response = await client.GetItemsAsync<object>( new LanguageParameter("es-ES"), new EqualsFilter("system.language", "es-ES") ); IList<object> items = response.Items;
    • PHP
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php // Defined by Composer to include required libraries require __DIR__ . '/vendor/autoload.php'; use Kontent\Ai\Delivery\DeliveryClient; $client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3'); $items = $client->getItems((new QueryParams()) ->language('es-ES') ->equals('system.language', 'es-ES'));
    // Tip: Find more about PHP SDKs at https://kontent.ai/learn/php // Defined by Composer to include required libraries require __DIR__ . '/vendor/autoload.php'; use Kontent\Ai\Delivery\DeliveryClient; $client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3'); $items = $client->getItems((new QueryParams()) ->language('es-ES') ->equals('system.language', 'es-ES'));
    • cURL
    curl --request GET \ --url 'https://deliver.kontent.ai/975bf280-fd91-488c-994c-2f04416e5ee3/items?language=es-ES&system.language=es-ES' \ --header 'content-type: application/json'
    curl --request GET \ --url 'https://deliver.kontent.ai/975bf280-fd91-488c-994c-2f04416e5ee3/items?language=es-ES&system.language=es-ES' \ --header 'content-type: application/json'
    • Ruby
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby require 'delivery-sdk-ruby' delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '975bf280-fd91-488c-994c-2f04416e5ee3' delivery_client.items(['system.language'.eq('es-ES')]) .language('es-ES') .execute do |response| items = response.items end
    # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby require 'delivery-sdk-ruby' delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '975bf280-fd91-488c-994c-2f04416e5ee3' delivery_client.items(['system.language'.eq('es-ES')]) .language('es-ES') .execute do |response| items = response.items end
    • TypeScript
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { createDeliveryClient } from '@kontent-ai/delivery-sdk'; const deliveryClient = createDeliveryClient({ environmentId: '975bf280-fd91-488c-994c-2f04416e5ee3', }); const response = await deliveryClient.items() .languageParameter('es-ES') .equalsFilter('system.language', 'es-ES') .toPromise();
    // Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript import { createDeliveryClient } from '@kontent-ai/delivery-sdk'; const deliveryClient = createDeliveryClient({ environmentId: '975bf280-fd91-488c-994c-2f04416e5ee3', }); const response = await deliveryClient.items() .languageParameter('es-ES') .equalsFilter('system.language', 'es-ES') .toPromise();

    What's next?

    You've learned how you to handle URLs in multilingual apps and two ways of retrieving translated content. If you know the content item's codename, you can request it directly and specify a language. When you need to request an item by its localized URL slug, use filters to get the item you need.