Ways to get localized content

Jan Cerman

5 minutes

0% complete

If you plan to display culture-specific content, your app needs to know how to retrieve content in specific languages.Depending on what you know about your content, there are a few ways to go about this.

Languages and localization

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

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

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.

// For other means of creating a client, see https://github.com/kontent-ai/delivery-sdk-net#setting-up-the-delivery-client
using var client = DeliveryClientBuilder
    .WithOptions(builder => builder
        .WithEnvironmentId("your-environment-id")
        .UseProductionApi()
        .Build())
    .Build();

// Tip: Generate models via https://github.com/kontent-ai/model-generator-net
// Gets a specific article in Spanish (with language fallbacks enabled by default)
var result = await client.GetItem<Article>("about_us")
    .WithLanguage("es-ES")
    .ExecuteAsync();

if (result.IsSuccess)
{
    Article item = result.Value.Elements;
}

What if the item doesn't exist in the specified language?The Delivery API checks the fallbacks of the specified language. If the content exists in the fallback language set for the requested language, you get the content item's content in the fallback language.

Get items by localized URL slug

Depending on how your app implements navigation and routing, you might want to request content items directly by their URL slugs. To retrieve a localized content item by its URL slug, you need to:

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

This approach requires querying all items within the project and filtering the results. Because the filtering is done by the Delivery API for you, there is no performance impact compared to requesting a specific content item.

// For other means of creating a client, see https://github.com/kontent-ai/delivery-sdk-net#setting-up-the-delivery-client
using var client = DeliveryClientBuilder
    .WithOptions(builder => builder
        .WithEnvironmentId("your-environment-id")
        .UseProductionApi()
        .Build())
    .Build();

// Tip: Generate models via https://github.com/kontent-ai/model-generator-net
// Filters all articles to find the Spanish variant by its URL slug
var result = await client.GetItems<Article>()
    .WithLanguage("es-ES")
    .Where(item => item.Element("url_pattern").IsEqualTo("acerda-de-nosotros"))
    .ExecuteAsync();

if (result.IsSuccess)
{
    IReadOnlyList<IContentItem<Article>> items = result.Value.Items;
}

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.

// For other means of creating a client, see https://github.com/kontent-ai/delivery-sdk-net#setting-up-the-delivery-client
using var client = DeliveryClientBuilder
    .WithOptions(builder => builder
        .WithEnvironmentId("your-environment-id")
        .UseProductionApi()
        .Build())
    .Build();

// Gets content items in Spanish without following language fallbacks
var result = await client.GetItems()
    .WithLanguage("es-ES", LanguageFallbackMode.Disabled)
    .ExecuteAsync();

if (result.IsSuccess)
{
    var items = result.Value.Items;
}

Sign in with your Kontent.ai credentials or sign up for free to unlock the full lesson, track your progress, and access exclusive expert insights and tips!