Ways to get localized content

Languages and localization

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

Get content in a specific language

To get localized content from your project, specify the language using the language's codename. For example, to get an article named About Us in Spanish, specify the item's codename and the language's codename.

Get items by localized URL slug

Depending on how you implement routing in your app, you might want to request content items by their URL slugs. If all you know about the content item is its URL slug, you need to request all items and filter them by the URL slug. This approach scales for both small and enterprise projects. To retrieve a localized content item by its URL slug, you need to do two things when making the API call:

Specify the language using the language’s codename, such as es-ES for Spanish.
Filter by the URL slug element’s value.

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

Ignoring language fallbacks

If you need to ensure you get content in only the specified language, you can filter out the content items that are in another language than specified. This effectively bypasses any language fallbacks. For example, this is how you retrieve content items translated into Spanish without any fallbacks.

The following table shows what content the API returns for specific combinations of language-related filters. The example assumes a 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 value	`system.language` parameter value	Behavior
`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-ES`	`es-ES`	The API returns only content items in Spanish. If an item is not translated to Spanish, the API doesn't return it.
`es-ES`	`en-US`	The 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.

// 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.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';

const deliveryClient = createDeliveryClient({
    environmentId: '975bf280-fd91-488c-994c-2f04416e5ee3',
});

const response = await deliveryClient.items()
    .languageParameter('es-ES')
    .equalsFilter('system.language', 'es-ES')
    .toPromise();