Multilingual content and localization
Context
Localization refers to the set of features and overall process of making an application accessible and consumable to a region or language. Localization needs to be thought of in distinct features, that may be applied together or separately to achieve the desired localization solution:
- Localized URLs
- Language code slugs
- Localized URLs and page names
- Multi-domain routing
- Language fallback
- Dictionary phrases
Execution
Keep in mind that with SitecoreAI, for each of the above of features or configurations, localization happens across two platforms that must be kept in alignment for the correct end user experience:
- Configuration of the SitecoreAI instance
- Configuration of the head application
Adding a language to SitecoreAI
Regardless of the feature being targeted, the SitecoreAI instance must be setup so that the SitecoreAI instance understands what is or is not a supported language.
To add a language to SitecoreAI, open up the Content Editor and navigate to /sitecore/system/Languages.
Right click the Languages item, choose Insert and then select Language. From there follow the wizard to add the desired language. Alternatively, you can add a new language version directly in SitecoreAI Portal Settings. After adding the language, perform a full site publish - consider the best practices needed for publishing, including setting up workflow. Review the Publishing to Edge recipe for more information.
Adding language versions of Content in SitecoreAI
Once the desired language has been setup you can add new language versions of existing content. A feature of SXA is that you can use a built-in script to create a new language version of the entire website. All site items and field values are copied from the source language to the target language. Alternatively, you can create language versions of individual items manually. In both cases your alternate language versions of content will be subject to the same workflow as the default language (workflow should be set on standard values so that new items are subject to workflow on creation). Where auto publish is not part of the workflow [and items are subject to bulk publishing] it’s worth remembering that where multiple language versions are concerned, the publishing times for a full site publish could be much greater due to the additional language versions involved.
Localized URLs
Language Code Slugs
Language code slugs refer to the part of the URL that indicate the requested language a page should be returned in. In the following URL www.mywebsite.com/fr-ca/about-us the first URL segment, /fr-ca/ is the considered the language slug and indicates that the page should be returned to the end user in the "French Canadian" language.
Localized page URLs and page names
Localized page URL’s and page names refers to when a page or route can be requested with a different name that differs from its canonical name and further implies the target or desired language the page should be returned in.
Using the following URL, www.mywebsite.com/about-us the canonical and implied language would be English. Following the steps below, you can configure both SitecoreAI and the head application to resolve the following URL as the same page, but for the French language: www.mywebsite.com/qui-sommes-nous
Sitecore does not allow for different item names based off the language version, however we can achieve localized functionality by using the Display Namefield of each item and updating the URL managers to use the Display Name field instead of the item name itself.
Patch Configuration for SitecoreAI
The following patch configuration file should be added to the Visual Studio solution and deployed to SitecoreAI. Be sure to check /sitecore/admin/showconfig.aspx to ensure the patch configuration has been appropriately applied:
After the patch configuration has been applied, perform a full site publish to rebuild all routes.
Configuring the Head Application
In the Next.JS application, the following configuration property needs to be updated to including ALL languages that were configured in SitecoreAI. The following configuration properties are located in next.config.js – typically at the root of the repository.
This configuration step should be done AFTER configuring SitecoreAI and publishing changes there. This configuration change to the next.config.js requires a redeployment.
In Content SDK 2.0 on the App Router, the proxy chain starts with LocaleProxy (locale, multisite, redirects, personalize). The code above is the earlier next.config.js setup. See the upgrade guide for the 2.0 locale handling. Redirects also changed in 2.0: when the URL has no locale, a redirect now goes to a URL without the default locale. To keep the earlier behavior, enable the Shall language be preserved upon redirect? checkbox in the SitecoreAI redirect rules.
After configuring both the SitecoreAI environment and Head application, Experience Edge will resolve routes based off the display name of the item. You can continue to resolve routes based off explicit language parameters (language code URL slugs, for example) in combination with the canonical item name.
Multi-domain routing with Localization
Multi-domain routing refers to the concept of using different URL’s within the same head application to target different languages.
Update the domains property in next.config.js and set a target language for each domain.
On lines 4-8, above, we have added a domain that will target the French Canadian language implicitly.
Language Fallback
When requesting an item in a specific language, and the language version for that item or route is not found, SitecoreAI (Experience Edge) will not resolve the item and return null or 404. You can configure SitecoreAI to “fallback” to a default language when a requested language version is not found on for an item.
Always use the site settings to configure language fallback in SitecoreAI.
Set the "Enable item language fallback" field on the Site Grouping item, locally in /sitecore/content/$tenant/$site/Settings/Site Grouping/$siteGrouping
Dictionary Phrases
Dictionary phrases are configured under the site (or in an shared site) at /sitecore/content/$tenantOrSiteCollection/$site/Dictionary.
To use a dictionary phrase in your head application, use the useI18n hook provided by the next-localization package.
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:
Using a different framework or no Sitecore SDK
This recipe shows localization with the Next.js and ASP.NET Core SDKs. In an application without a Sitecore SDK, your code resolves the language for each request and passes it to the layout query. The Routing, localization, and multi-sites page covers locale resolution.
Related Recipes
Related Documentation
- For recipe suggestions, questions or feedback, please use the form.
- For direct contribution, please create a pull request on the Github repository for review.