---
title: "Supporting multilingual applications in JSS"
slug: "supporting-multilingual-applications-in-jss"
abstract: "Overview of how JSS apps handle multilingual content and dictionaries"
---
# Supporting multilingual applications in JSS

Sitecore JSS allows you to take advantage of the content language versioning feature of Sitecore.

There are typically two concerns with rendering translated data from Sitecore:

- The primary page content.
- Dictionary items used for translation of labels, button text, and so on.

The sample apps show one approach to using the tools provided by JSS to make your app fully translatable.

## Rendering translated Sitecore content

When getting content from Sitecore, whether with GraphQL or with REST, the request is made behind the scenes to the [Sitecore Layout Service](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/layout-service.html "Layout Service").

The Layout Service respects the Sitecore Language Context when fetching route and context data, meaning that requests to the Layout Service can utilize the `sc_lang` parameter to request content in a specific language. For example, `http://JssReactWeb/sitecore/api/layout/render/jss?item=/Services&sc_lang=es-MX&sc_apikey={YOUR_API_KEY}`.

You can choose how you [invoke the Layout Service](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/fetching-layout-data-with-the-jss-layout-api.html "Fetching layout data with the JSS Layout API") and handle language changes.

If you set up your JSS project using one of the sample applications, your application already handles the fetching of layout data.

## Acquiring Sitecore dictionary phrases

Sitecore JSS provides a [Dictionary API](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/jss-dictionary-api.html "JSS Dictionary API") to help you [acquire translated phrases in a JSS app](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/fetching-dictionary-data-with-the-jss-dictionary-api.html "Fetching dictionary data with the JSS Dictionary API").

If you set up your JSS project using one of the sample applications, your application already handles the fetching of dictionary phrases.

## Translated route and context data in disconnected mode

To simulate translated content when running the application in [disconnected mode](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/start-a-jss-app-in-disconnected-mode.html "Start a JSS app in disconnected mode"), the Disconnected Layout Service provided by JSS sample applications 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, the service regenerates the manifest automatically when a different language is requested by the app. Data must be available in multiple languages to support this use case.

> [!note]
> The Disconnected Layout Service is not used when you develop using the [Sitecore-first development workflow](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/sitecore-first-development-workflow.html "Sitecore-first development workflow").

The sample apps have a default convention of using `lang.yml` or JSON files to enable the definition of content and layout data for different languages.

![Content and layout data definitions for multiple languages in disconnected mode](https://doc.sitecore.com/api/markdown-image/xp/en/developers/hd/23/sitecore-headless-development/images/recipe-content-translation-dev-routes.png)

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.

### Translated content and disconnected mode import

In most cases, an application developed while working without a Sitecore instance will probably transition to using Sitecore data before translation is a consideration.

However, it is possible to develop disconnected multilingual content while working without a Sitecore instance. This technique is demonstrated in the sample apps, by defining routes using a file for each language, such as `en.yaml` and `es-mx.yaml`.

To deploy a multilingual disconnected application, you must deploy the application for each language, separately, because:

- The app has a single default language, defined in the `package.json` file. All sample apps default to `en`.
- When [generating a manifest](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/generating-a-jss-app-manifest-file.html "Generating a JSS app manifest file"), the manifest contains only one language at a time.
- When deploying an update package, only one language is included in the package at a time.
- The default language when manifesting or packaging is the one defined in `package.json`

> [!note]
> If you are not deploying content/route data using the arguments `--includeContent` or `--includeDictionary`, you do not deploy multilingual data and can, therefore, deploy in a single step.

To deploy your items to Sitecore for a language:

- In a terminal, in the root directory of your JSS application, run the following command:

    ```shell
    jss deploy items --language=es-MX --includeContent --includeDictionary
    ```

    > [!note]
    > The `jss deploy items` command does not deploy files.
    >
    > To deploy files use the `jss deploy files` command.
    >
    > To deploy items and files use the `jss deploy app` command.

Repeat the step for each language you want to deploy.

## Translated content and integrated rendering

When the JSS application runs in [integrated mode](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/start-a-jss-app-in-integrated-mode.html "Start a JSS app in integrated mode"), because Sitecore handles language resolution and Layout Service content provided to the `renderView()` function used for [integrated server-side rendering](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/server-side-rendering-jss-apps-in-integrated-mode.html "Server-side rendering JSS apps in integrated mode"), the data returns in the correct language.

To assist with content translation, JSS adds two properties to the `viewBag` argument:

- `viewBag.language` - this is the language resolved by Sitecore, helpful for initializing the app state with the correct language. Because Sitecore also uses a language cookie by default, a request without a language parameter in the URL can return content in the language last requested by the user.
- `viewBag.dictionary` - contains the dictionary phrases for the app in the current language as provided by the [Sitecore Dictionary Service](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/dictionary-service.html "Dictionary Service"). This allows initializing the dictionary for server-side rendering.

## Translated content in headless server-side rendering mode

The [headless server-side rendering](https://doc.sitecore.com/xp/en/developers/hd/23/sitecore-headless-development/headless-server-side-rendering-mode.html "Headless server-side rendering mode") 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 want the proxy to append a language parameter. To facilitate this, the proxy function accepts an optional `parseRouteUrl` function that it expects to return an object with `lang` and `sitecoreRoute` properties.

The example populates this function with the exported function `parseRouteUrl`. You can inspect a server bundle for React and Vue.js sample apps in the `/server/server.js` file or, for Angular apps, in the `server.bundle.ts` file.