Multilingual content and localization

In the Next.JS application, the following configuration property needs to be updated to including ALL languages that were configured in XM Cloud. The following configuration properties are located in next.config.js – typically at the root of the repository.

i18n: {
// These are all the locales you want to support in your application.
// These should generally match (or at least be a subset of) those in Sitecore.
locales: ['en', 'fr-CA', 'es'],
// This is the locale that will be used when visiting a non-locale
// prefixed path e.g. `/styleguide`.
defaultLocale: jssConfig.defaultLanguage
}

This configuration step should be done AFTER configuring XM Cloud and publishing changes there. This configuration change to the next.config.js requires a redeployment.

In the ASP.NET Core application, the following configuration property needs to be updated to including ALL languages that were configured in the XM Cloud environment.

Those configuration properties are located in Program.cs – typically, at the root of the Head app folder, for example in \headapps\aspnet-core-starter\Program.cs.

const string defaultLanguage = "en";
const string germanLanguage = "de-DE";
app.UseRequestLocalization(options =>
    {
        // If you add languages in Sitecore which this site / Rendering Host should support, add them here.
        List<CultureInfo> supportedCultures = [new CultureInfo(defaultLanguage), new CultureInfo(germanLanguage)];
        options.DefaultRequestCulture = new RequestCulture(defaultLanguage, defaultLanguage);
        options.SupportedCultures = supportedCultures;
        options.SupportedUICultures = supportedCultures;
        options.UseSitecoreRequestLocalization();
    });

You can move out those settings to the appsettings.json file for better development and configuration experience.

🚀 Coming soon.

Update the domains property in next.config.js and set a target language for each domain.

i18n: {
locales: ['en', 'fr-CA'],
defaultLocale: jssConfig.defaultLanguage,
domains: [
{
domain: 'www.mywebsiteinfrench.com',
defaultLocale: 'fr-CA',
},],
},

On lines 4-8, above, we have added a domain that will target the French Canadian language implicitly.

To implement this feature in ASP.NET Core SDK you need to create a custom request culture provider and add it to the RequestCultureProviders collection in RequestLocalizationOptions property into correct place between OOTB providers.

An example of the provider class:

using Microsoft.AspNetCore.Localization;
namespace Sitecore.AspNetCore.Starter.Extensions
{
 public class HostnameRequestCultureProvider : RequestCultureProvider
 {
   public override Task<ProviderCultureResult?> DetermineProviderCultureResult(HttpContext httpContext)
   {
     ArgumentNullException.ThrowIfNull(httpContext);
     // Depeneding on the hostname used, set the culture accordingly so that
     // there is no need to use language prefix or query string parameter to switch language
     var culture = httpContext.Request.Host.Host switch
     {
       "testsite.nl" => "nl-NL",
       "testsite.de" => "de-DE",
       _ => "en", // Default to English if no match found
     };
     return Task.FromResult<ProviderCultureResult?>(new ProviderCultureResult(culture, culture));
   }
 }
}

A snipped of the Program.cs showing the registration of this provider (check out the code comments in the snipped for more information):

// example of adding several languages to be supported by the application
const string defaultLanguage = "en";
const string germanLanguage = "de-DE";
const string dutchLanguage = "nl-NL";
app.UseRequestLocalization(options =>
   {
       //List<CultureInfo> supportedCultures = [new CultureInfo(defaultLanguage)];
       // If you add languages in Sitecore which this site / Rendering Host should support, add them here.
       List<CultureInfo> supportedCultures = [new CultureInfo(defaultLanguage), new CultureInfo(germanLanguage), new CultureInfo(dutchLanguage)];
       options.DefaultRequestCulture = new RequestCulture(defaultLanguage, defaultLanguage);
       options.SupportedCultures = supportedCultures;
       options.SupportedUICultures = supportedCultures;
       options.UseSitecoreRequestLocalization();
       // Custom request culture provider that should be placed after Sitecore ASP.NET SDK providers
       // and before the provider "Microsoft.AspNetCore.Localization.AcceptLanguageHeaderRequestCultureProvider"
       // In this case app will support both setting localization by hostnam
       // and OOTB Sitecore localization resolving by language prefix or query string parameter
       // this might be the case when you want to have a default language set per hostname
       // and still allow users to switch languages using language prefix or query string parameter
       options.RequestCultureProviders.Insert(4, new HostnameRequestCultureProvider());
   }); 

Line 22 adds the custom provider to the collection at index 4.

This will ensure that the locale will be set according to the host name. At the same time OOTB locale resolving (by URL prefix or sc_lang parameter) will work as well. This helps to cover the use cases when non EN locale should be site for some websites by default, but the site should still support switching language by using URL prefix.

🚀 Coming soon.

To use a dictionary phrase in your head application, use the useI18n hook provided by the next-localization package.

import { useI18n } from 'next-localization';
const MultilingualComponent = (): JSX.Element => {
const { t, locale } = useI18n();
return (
<div>
<p>Translated text: {t('dictionary-phrase')}</p>
<p>The current language is: {locale()}</p>
</div>
);
};
export default MultilingualComponent;

The dictionary-factory-service in the foundation head repository will provide access to all dictionary phrases for a site. You can also directly query for dictionary phrases using the following GraphQL query:

query DictionarySearch($rootItemId: String!, $language: String!, $templates: String!, $pageSize: Int = 10, $after: String) {
  search(where: { AND: [{ name: "_path", value: $rootItemId, operator: CONTAINS }, { name: "_language", value: $language }, { name: "_templates", value: $templates, operator: CONTAINS }] }, first: $pageSize, after: $after) {
    total
    pageInfo {
      endCursor
      hasNext
    }
    results {
      key: field(name: "Key") {
        value
      }
      phrase: field(name: "Phrase") {
        value
      }
    }
  }
}

ASP.NET Core SDK does not support simple dictionary phrases translation similarly to Next.JS implementation yet. The feature is in the backlog and should be implemented in the future.

There is however dictionary service implementation that can be used as a workaround. It still requires some additional implementation to make dictionary service usage more efficient. Currently it is possible to only fetch the whole dictionary for a website. It is surely make sanse to implement this as a service independently of any component and cache dictionary values (with proper invalidation strategy).

To use dictionary service, register it in Program.cs file:

builder.Services.AddSitecoreRenderingEngine(options =>
                    {
                      options.AddStarterKitViews()
                              .AddViewComponent("DictionarySample-Component", "DictionarySample")
                             .AddDefaultPartialView("_ComponentNotFound");                               
                    })
                .ForwardHeaders()
                .WithSitecorePages(sitecoreSettings.EdgeContextId ?? string.Empty, options => { options.EditingSecret = sitecoreSettings.EditingSecret; });
builder.Services.AddSingleton<IDictionaryService, DictionaryService>();
WebApplication app = builder.Build();

Below is an example of simple dictionary service usage from a component.

Note the example is not a best practice, since it fetches the whole dictionary in View Component at every rendering.

using GraphQL.Client.Abstractions;
using Microsoft.AspNetCore.Mvc;
using Sitecore.AspNetCore.SDK.Pages.Services;
namespace Sitecore.AspNetCore.Starter.ViewComponents
{
public class DictionarySampleViewComponent : ViewComponent
{
private readonly IDictionaryService _dictionaryService;
private readonly IGraphQLClient _graphQLClient;
public DictionarySampleViewComponent(IDictionaryService dictionaryService, IGraphQLClient graphQLClient)
{
_dictionaryService = dictionaryService ?? throw new ArgumentNullException(nameof(dictionaryService));
_graphQLClient = graphQLClient ?? throw new ArgumentNullException(nameof(graphQLClient));
}
public async Task<IViewComponentResult> InvokeAsync()
{
var scContext = HttpContext.GetSitecoreRenderingContext();
// Ensure scContext and its nested properties are not null before accessing them
if (scContext?.Response?.Content?.Sitecore?.Context == null)
{
  return View("DictionarySample", "Error: Sitecore context is not available.");
}
// Getting Site name and Language from the Sitecore context - we need it to get values from dictionary
var language = scContext.Response.Content.Sitecore.Context.Language;
var siteName = scContext.Response.Content.Sitecore.Context.Site?.Name ?? "defaultSite"; // Fallback to a default site name if null
// Get the entire dictionary for the site and language.
// NOTE: not a good practice to fetch entire dictionary every time within the single component invocation.
// Consider caching or fetching only the required keys for performance optimization. Wait for the feature to be implemented for Sitecore ASP.NET Core SDL
// or create to fetch and cache dictionary items as needed (don't forget about cache invalidation).
var dictionary = await _dictionaryService.GetSiteDictionary(siteName, language, _graphQLClient);
// Lookup the translation for the given key using LINQ
var translation = dictionary.FirstOrDefault(item => item.Key == "HelloWorld")?.Value
    ?? "[Key not found: 'HelloWorld']";
return View("DictionarySample", translation);
}
}
}

🚀 Coming soon.