Support for Right-to-left Languages in the Responsive Components and Templates

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

You can use the responsive components and templates to display content in right-to-left languages such as Arabic.

Important: Right-to-left support in APL requires APL 1.7 or later and the alexa-layouts package 1.4.0 or later.

Right-to-left support in the components and templates

The responsive components and templates display content in either a left-to-right or right-to-left reading direction.

For example, the AlexaHeader component displays an optional back button, header title text, attribution text or an attribution icon. The following images show the difference between the left-to-right and right-to-left reading directions.

The left-to-right orientation displays the back button and the header title text on the left and the attribution text/image on the right

The right-to-left orientation displays the back button and header title text on the right and the attribution text/image on the left

Some components don't display text, but users still read and interact with the content in a reading direction. For example, the AlexaProgressBar displays a bar that shows ongoing activity or progress. For left-to-right, the bar starts on the left and moves to the right to show completion. For right-to-left, the bar starts on the right and moves to the left.

The following image shows how a progress bar looks in both left-to-right and right-to-left orientation. Both versions of the bar represent two minutes of total time with one minute elapsed.

Examples of the same progress bar displayed left-to-right and right-to-left

Components that don't display content in a reading direction, such as AlexaBackground and AlexaCheckbox, don't provide any support for the right-to-left layout direction.

Language-specific fonts in the components and templates

Some devices provide language-specific fonts. For example, a device might support an Arabic version of the standard fonts. The responsive components and templates that display text support using these fonts.

The following images show the AlexaButton and AlexaFooter components with the default fonts and with Arabic-specific fonts.

AlexaButton and AlexaFooter using the default fonts and left-to-right layout

AlexaButton and AlexaFooter using Arabic-specific fonts and the right-to-left layout

Set the layout direction and language

Use the layoutDirection and lang properties to set the layout direction and language. The layoutDirection property accepts the values LTR or RTL. The lang property accepts standard locale codes. For example, to use Arabic-specific fonts, set lang to ar-SA.

You can set these properties at different places within your document, depending on the layout you are creating.

Use the document-level environment property to set the default layoutDirection and lang properties for the entire document. The responsive components and templates use the document-level properties by default. This is the recommended method, as you set the values in one place for the entire document.
When you need to override the document-level settings on an individual component, set the layoutDirection property for the individual component or its parent container.
- You can set the layoutDirection property on each component that supports right-to-left content.
- You can set the lang property on each component that displays text.
Some responsive components can inherit layoutDirection from the parent component. For example, you can set the property on the Container, and the responsive component inside that Container inherits the layoutDirection value. See the documentation for a given responsive component to determine whether the component can inherit layoutDirection.

Always use data-binding to set the layoutDirection and lang properties to values in your data source. When your skill constructs the data source to send with the RenderDocument directive, set these properties in the data source based on the locale provided in the request. This method lets you use the same APL document for both left-to-right and right-to-left content.

Important: The environment document property requires APL 1.8 or later. When supporting APL 1.7, bind your data source to the layoutDirection and lang properties on the top-level Container instead. For details, see Support for Right-to-left Languages in the Responsive Components and Templates (APL 1.7).

To set the layout direction and language for the entire document

In your document, add the environment property at the top level.

 {
     "type": "APL",
     "version": "2024.3",
     "environment": {}
 }

Bind the environment.layoutDirection and environment.lang properties to properties in your data source.

 {
     "type": "APL",
     "version": "2024.3",
     "environment": {
         "layoutDirection": "${bindExample.requestLanguage.layoutDirection}",
         "lang": "${bindExample.requestLanguage.lang}"
     }
 }

Add a reference to your data source in the environment.parameters property.

The following example binds the document-level environment properties to values in a data source called bindExample.

 {
     "type": "APL",
     "version": "2024.3",
     "environment": {
         "layoutDirection": "${bindExample.requestLanguage.layoutDirection}",
         "lang": "${bindExample.requestLanguage.lang}",
         "parameters": [
             "bindExample"
         ]
     }
 }

In your mainTemplate, make sure that you include the same data source name in the parameters property.

 {
     "mainTemplate": {
         "parameters": [
             "bindExample"
         ],
         "items": []
     }
 }

Add the responsive components or a template to the items array in mainTemplate. The components automatically default to use the values set in environment.layoutDirection and environment.lang.
In your skill, set the properties in your data source to reflect the layout direction and language, based on the locale of the user's request.

The following example shows an excerpt of a data source that sets the layout direction and language for Arabic content. The skill code sets bindExample.requestLanguage.layoutDirection and bindExample.requestLanguage.lang based on the user's locale.
```
 {
     "bindExample": {
         "requestLanguage": {
             "layoutDirection": "RTL",
             "lang": "ar-SA"
         },
         "properties": {
             // properties for the content to display in the document
         }
     }
 }
```

The following example shows an APL document that displays multiple responsive components, as well as primitive Text components. All of the components display either left-to-right or right-to-left depending on the properties in the bindExample data source.

Copied to clipboard.

To learn how to test APL examples in the authoring tool, see Experiment with APL Examples in the Authoring Tool.

{
    "type": "APL",
    "version": "2024.3",
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.7.0"
        }
    ],
    "environment": {
        "layoutDirection": "${bindExample.requestLanguage.layoutDirection}",
        "lang": "${bindExample.requestLanguage.lang}",
        "parameters": [
            "bindExample"
        ]
    },
    "mainTemplate": {
        "parameters": [
            "bindExample"
        ],
        "items": [
            {
                "type": "Container",
                "width": "100%",
                "height": "100%",
                "items": [
                    {
                        "type": "AlexaBackground"
                    },
                    {
                        "type": "AlexaHeader",
                        "headerTitle": "${bindExample.properties.title}",
                        "headerBackButton": true
                    },
                    {
                        "type": "Container",
                        "paddingStart": "@marginHorizontal",
                        "paddingEnd": "@marginHorizontal",
                        "paddingTop": "@spacingLarge",
                        "grow": 1,
                        "items": [
                            {
                                "type": "Text",
                                "text": "The layoutDirection is: ${environment.layoutDirection}"
                            },
                            {
                                "type": "Text",
                                "text": "The lang is: ${environment.lang}"
                            },
                            {
                                "type": "Text",
                                "text": "${bindExample.properties.textContent.textBlock1.text}",
                                "spacing": "@spacingMedium"
                            },
                            {
                                "type": "AlexaRating",
                                "ratingNumber": "${bindExample.properties.rating.number}",
                                "ratingText": "${bindExample.properties.rating.text}",
                                "spacing": "@spacingMedium"
                            }
                        ]
                    },
                    {
                        "type": "AlexaFooter",
                        "hintText": "${bindExample.properties.hintText}"
                    }
                ]
            }
        ]
    }
}

The following images show this document in both left-to-right and right-to-left orientations.

Result when layoutDirection is 'LTR' and lang is 'en-US'

Result when layoutDirection is 'RTL' and lang is 'ar-SA'

This process works the same way for responsive templates. A responsive template is a complete viewport design that fills the entire viewport. You don't normally combine the template with other components.

The following examples show a document that uses the AlexaHeadline template and two data sources, one with English content and one with Arabic content. The data source specifies the values to use for layoutDirection and lang, so the AlexaHeadline template automatically adjusts.

The following images show the results for both the English and Arabic examples.

AlexaHeadline template when layoutDirection is 'LTR' and lang is 'en-US'

AlexaHeadline template when layoutDirection is 'RTL' and lang is 'ar-SA'

Components and templates with right-to-left support

The following responsive components display in left-to-right or right-to-left:

The following responsive templates display in left-to-right or right-to-left:

Was this page helpful?

Provide feedback