Sitecore JSS has been built to allow you to take advantage of one of Sitecore's strongest WCM features -- content language versioning. Typically there are two concerns with translation: the primary page/route content, and "dictionary" items which may be used throughout an app/site for miscellaneous labels, button text, etc.
The sample apps shows one approach to using the tools provided by JSS to make your app fully translatable.
Translation of Layout Service Content
The Layout Service will fully respect the Sitecore Language Context when fetching route and context data. This means that requests to the Layout Service can utilize the
sc_lang param to request content in a specific language.
It's up to you how the Layout Service is invoked in your app, and how language changes are handled. In the sample apps, the
SitecoreContentService implementation accepts
language as parameter when getting route data.
Translated Route and Context Data in Dev/Disconnected Mode
In order to simulate translated content from the Layout Service, the Disconnected Layout Service mocks the interface of the Sitecore Layout Service including the language data. The Disconnected Layout Service is powered by the JSS Manifest data, which is single-language. However, DLS re-generates the manifest on the fly when a different language is requested by the app. Data needs to be available in multiple languages to support this use case; the sample apps have a default convention of using
lang.yml (or JSON) files to enable definition of different languages' contents and layout.
This is only the default convention for multilingual content for sample apps, defined in
/sitecore/definitions/routes.sitecore.js. You can define your own conventions and ways to store multilingual data that matches your preferences and needs.
Note: when operating in Sitecore-first development workflow, disconnected layout service is not used.
Translation of Dictionary Items
Sitecore JSS provides an additional REST Dictionary Service to support acquiring translated phrases in your app. The sample apps demonstrate using this service to translate static text.
Language Routing / Language in URL
JSS does not dictate your route/URL structure, however it's much simpler to implement integrated mode (and thus allowing Sitecore authors to edit the content of the site) when the routing structure follows Sitecore's route item structure. All sample apps implement basic routing that follows the Sitecore route item hierarchy by default. The default router can be replaced at need; the sample apps are intended to be samples to take and modify.
The sample apps demonstrate routing using language prefixes (i.e. both
/es-MX/about are supported formats).
Translated Content and Integrated Rendering
In integrated mode, Sitecore handles language resolution and thus Layout Service content provided to the
renderView() SSR function will be returned in the correct language for server rendering. In addition, by default JSS adds two properties to the
viewBag argument to assist in language translation:
viewBag.language- This is the language resolved by Sitecore, helpful for initializing app state to the correct language. Since Sitecore also uses a language cookie by default, a request without language in the URL can return content in the language last requested by the user.
viewBag.dictionary- The dictionary phrases for the app in the current language, i.e. what would be the output of the Dictionary Service. This allows initializing the dictionary for server-side rendering. For an example of usage, see
i18n.jsand how it is invoked in both
Translated Content and Disconnected Mode Import
In most cases, a disconnected mode application will probably transition to being a Sitecore-based application (i.e. run in connected mode or integrated mode) before translation is a consideration. However, it is possible to develop disconnected multilingual content. This technique is demonstrated in the advanced app samples, by defining routes using a file for each language, e.g.
It's important to know that when doing multilingual disconnected mode applications:
- The app still has a single default language (defined in
package.json). All sample apps default to
- When generating a manifest, the manifest contains only one language at a time
- When deploying an update package, similar to the manifest, only one language is included in the package at a time
- The default language when manifesting or packaging is the one defined in
To deploy a multilingual disconnected application, each language's data must be separately deployed.
Note that if you are not deploying content/route data (e.g. not using the
--includeDictionaryarguments), there is no multilingual concern and deployment is a single-step process.
To deploy each language issue a deployment command using the
--language parameter, like this:
jss deploy items --language=es-MX --includeContent --includeDictionary
jss deploy itemsdoes not deploy files. To deploy files use
jss deploy files. To deploy items and files use
jss deploy app.
Headless Mode / Layout Service Proxying
The headless server-side rendering example included with JSS works in part by translating and proxying the initial route URL into a request to the Layout Service. This requires some intelligence on the structure of your route URLs, if they contain anything other than the Sitecore route path, or if you wish the proxy to append a language parameter. To faciliate this, the proxy function accepts an optional
parseRouteUrl function, which it expects to return an object with
The example populates this function with a
parseRouteUrl export from your app's server bundle. See the server file in your sample app (e.g.
/server/server.js for React).