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

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

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.

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.

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.

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.

To set the layout direction and language for the entire document

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

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

2. 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}"
        }
    }
   

3. 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"
            ]
        }
    }
   

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

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

5. 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.

6. 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.

Example document: Binding layout direction and language at the document level  

{
    "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}"
                    }
                ]
            }
        ]
    }
}

Data source: Binding layout direction and language at the document level  

{
    "bindExample": {
        "requestLanguage": {
            "layoutDirection": "LTR",
            "lang": "en-US"
        },
        "properties": {
            "title": "Bind layout and language data at the document level",
            "textContent": {
                "textBlock1": {
                    "type": "PlainText",
                    "text": "This example shows how to bind your data source to the document-level <code>layoutDirection</code> and <code>lang</code> properties. The properties default these settings for the responsive components displayed in the document."
                }
            },
            "rating": {
                "number": 3.5,
                "text": "Rating Text"
            },
            "hintText": "This is the hint text displayed in AlexaFooter"
        }
    }
}

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

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.

Example document: Use AlexaHeadline for both English and Arabic  

{
    "type": "APL",
    "version": "2024.3",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.7.0"
        }
    ],
    "environment": {
        "layoutDirection": "${headlineData.responseLanguage.layoutDirection}",
        "lang": "${headlineData.responseLanguage.language}",
        "parameters": [
            "headlineData"
        ]
    },
    "mainTemplate": {
        "parameters": [
            "headlineData"
        ],
        "items": [
            {
                "type": "AlexaHeadline",
                "headerTitle": "${headlineData.textContent.title}",
                "headerSubtitle": "${headlineData.textContent.subTitle}",
                "headerAttributionImage": "https://s3.amazonaws.com/ask-skills-assets/apl-layout-assets/attribution_dark_hub_prime.png",
                "headerBackButton": true,
                "headerDivider": false,
                "headerBackButtonAccessibilityLabel": "back",
                "primaryText": "${headlineData.textContent.primaryText}",
                "secondaryText": "${headlineData.textContent.secondaryText}",
                "footerHintText": "${headlineData.textContent.footerHintText}"
            }
        ]
    }
}

Data source: English data for AlexaHeadline example  

{
    "headlineData": {
        "description": "Example of a data source the skill provides for an English request.",
        "responseLanguage": {
            "layoutDirection": "LTR",
            "language": "en-US"
        },
        "textContent": {
            "title": "This is the header title",
            "subTitle": "This is the header subtitle",
            "primaryText": "This is the main headline text. The text truncates depending on the size of the viewport. For example, a large hub displays up to four lines, but a smaller hub displays up to two lines.",
            "secondaryText": "This is the secondary text. It is limited to a single line. So very long secondary text is truncated",
            "footerHintText": "This is the hint text to suggest phrases users can say"
        },
        "headerAttributionImage": "https://s3.amazonaws.com/ask-skills-assets/apl-layout-assets/attribution_dark_hub_prime.png"
    }
}

Data source: Arabic data for AlexaHeadline example  

{
    "headlineData": {
        "description": "Example of a data source the skill provides for an Arabic request.",
        "responseLanguage": {
            "layoutDirection": "RTL",
            "language": "ar-SA"
        },
        "textContent": {
            "title": "هنا العنوان الرئيسي",
            "subTitle": "هنا العنوان الفرعي",
            "primaryText": "هنا نص العنوان الرئيسي. يتم اقتطاع النص بناءً على حجم إطار العرض. على سبيل المثال، يعرض اطار العرض الكبير ما يصل إلى أربعة اسطر، بينما يعرض اطار العرض الأصغر ما يصل إلى سطرين",
            "secondaryText": "هنا النص الثانوي ويقتصر على سطر واحد فقط. يتم اقتطاع النص الثانوي الطويل جدًا",
            "footerHintText": "هنا نص التلميح لاقتراح عبارات يمكن للمستخدمين قولها"
        },
        "headerAttributionImage": "https://s3.amazonaws.com/ask-skills-assets/apl-layout-assets/attribution_dark_hub_prime.png"
    }
}

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

Components and templates with right-to-left support

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

• AlexaButton
• AlexaFooter
• AlexaHeader
• AlexaImageListItem
• AlexaProgressBar
• AlexaRating
• AlexaSlider
• AlexaSwipeToAction
• AlexaSwitch
• AlexaTextListItem

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

• AlexaDetail
• AlexaGridList
• AlexaHeadline
• AlexaImageList
• AlexaLists
• AlexaPaginatedList
• AlexaTextList

Related topics

• Base Component Properties
• layoutDirection component property
• Text Component
• EditText Component
• Responsive Components
• Responsive Templates