Support for Right-to-left Languages in the Responsive Components and Templates (APL 1.7)

(This is not the most recent version of this document. Use the Other Versions option to see the documentation for the most recent version of this document)

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

The responsive components and templates provide properties to set the layout direction and language:

• The layoutDirection property is available on each component and template that supports right-to-left content. Set layoutDirection to either LTR or RTL.

  Some responsive components can inherit layoutDirection from the parent component. See the documentation for a given responsive component to determine whether the component can inherit layoutDirection.

• The lang property is available on each component and template that displays text. Set lang to the locale code for the content. For example, to use Arabic-specific fonts, set lang to ar-SA.

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.

Bind layoutDirection and lang on a component

To set the layout direction and language for a responsive component

1. In the top-level Container component in your template, create bind variables called LayoutDirection and Lang. Bind these properties to properties your data source. Capitalize the names of these custom properties to distinguish them from the component properties layoutDirection and lang.

   The following example shows a Container that creates two bind variables. The variables get their values from a data source called bindExample. All child components of this Container have access to these bind variables.

    {
        "type": "Container",
        "width": "100%",
        "height": "100%",
        "bind": [
            {
                "name": "LayoutDirection",
                "value": "${payload.bindExample.requestLanguage.layoutDirection}"
            },
            {
                "name": "Lang",
                "value": "${payload.bindExample.requestLanguage.lang}"
            }
        ],
        "items": []
    }
   

2. Set the layoutDirection on the Container to the bound variable.

   Primitive APL components can inherit the layoutDirection from the parent component, so it's useful to set this property on the Container as well. Some responsive components can also inherit this value. See the documentation for a given responsive component to determine whether the component inherits layoutDirection from the parent container or not.

    "layoutDirection": "${LayoutDirection}"
   

3. Add the responsive component to the Container and bind the layoutDirection on the responsive component to the bound variable. If the component displays text, also bind lang to the bound variable.

    {
        "type": "AlexaRating",
        "ratingNumber": "${payload.bindExample.properties.rating.number}",
        "ratingText": "${payload.bindExample.properties.rating.text}",
        "spacing": "@spacingMedium",
        "layoutDirection": "${LayoutDirection}",
        "lang": "${Lang}"
    }
   

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

    {
        "bindExample": {
            "type": "object",
            "objectId": "bindExample",
            "requestLanguage": {
                "layoutDirection": "RTL",
                "lang": "ar-SA"
            },
            "properties": {}
        }
    }
   

The following document and data source examples illustrate placing responsive components in a Container and setting the layoutDirection and lang properties:

• The top-level Container creates bind variables for both properties and also sets layoutDirection.
• The primitive Text component and AlexaFooter responsive component can both inherit layoutDirection from the Container. Therefore, these components don't set layoutDirection. Because these components display text, they also set lang to use language-specific fonts.
• The AlexaHeader and AlexaRating responsive components can't inherit layoutDirection from the Container. Therefore, these components set both layoutDirection and lang.
• The AlexaBackground responsive component doesn't display any text or other content that needs a reading direction, so it doesn't include layoutDirection or lang.

Example document: Setting layout direction and language  

{
    "type": "APL",
    "version": "1.7",
    "license": "Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.\nSPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0\nLicensed under the Amazon Software License  http://aws.amazon.com/asl/",
    "settings": {},
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.7.0"
        }
    ],
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "width": "100%",
                "height": "100%",
                "bind": [
                    {
                        "name": "LayoutDirection",
                        "value": "${payload.bindExample.requestLanguage.layoutDirection}"
                    },
                    {
                        "name": "Lang",
                        "value": "${payload.bindExample.requestLanguage.lang}"
                    }
                ],
                "layoutDirection": "${LayoutDirection}",
                "items": [
                    {
                        "type": "AlexaBackground"
                    },
                    {
                        "type": "AlexaHeader",
                        "headerTitle": "${payload.bindExample.properties.title}",
                        "headerBackButton": true,
                        "layoutDirection": "${LayoutDirection}",
                        "lang": "${lang}"
                    },
                    {
                        "type": "Container",
                        "paddingStart": "@marginHorizontal",
                        "paddingEnd": "@marginHorizontal",
                        "paddingTop": "@spacingLarge",
                        "grow": 1,
                        "items": [
                            {
                                "type": "Text",
                                "text": "${payload.bindExample.properties.textContent.textBlock1.text}",
                                "spacing": "@spacingMedium",
                                "lang": "${Lang}"
                            },
                            {
                                "type": "AlexaRating",
                                "ratingNumber": "${payload.bindExample.properties.rating.number}",
                                "ratingText": "${payload.bindExample.properties.rating.text}",
                                "spacing": "@spacingMedium",
                                "layoutDirection": "${LayoutDirection}",
                                "lang": "${Lang}"
                            }
                        ]
                    },
                    {
                        "type": "AlexaFooter",
                        "hintText": "${payload.bindExample.properties.hintText}",
                        "lang": "${Lang}"
                    }
                ]
            }
        ]
    }
}

Data source: Binding layout direction and language  

{
    "bindExample": {
        "type": "object",
        "objectId": "bindExample",
        "requestLanguage": {
            "layoutDirection": "LTR",
            "lang": "en-US"
        },
        "properties": {
            "title": "Bind layout and language data for responsive components",
            "textContent": {
                "textBlock1": {
                    "type": "PlainText",
                    "text": "This example shows how to bind your data source to the <code>layoutDirection</code> and <code>lang</code> properties on responsive components."
                }
            },
            "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.

Bind layoutDirection and lang on a template

A responsive template is a complete viewport design that fills the entire viewport. You don't normally combine the template with other components.

Place the template in the mainTemplate section of the document and bind the layoutDirection and lang properties on the template to properties in your data source.

To set the layout direction and language for a responsive template

1. Add the template to the mainTemplate property of the APL document.

2. Bind the layoutDirection and lang properties on the template to properties in your data source.

   The following example shows the AlexaHeadline template with the layoutDirection and lang properties bound to the data source.

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

3. 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 the AlexaHeadline example.

    {
        "headlineData": {
            "responseLanguage": {
                "layoutDirection": "RTL",
                "language": "ar-SA"
            },
            "textContent": {}
        }
    }
   

The following examples show the complete document 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": "1.7",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.7.0"
        }
    ],
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "AlexaHeadline",
                "layoutDirection": "${payload.headlineData.responseLanguage.layoutDirection}",
                "lang": "${payload.headlineData.responseLanguage.language}",
                "headerTitle": "${payload.headlineData.textContent.title}",
                "headerSubtitle": "${payload.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": "${payload.headlineData.textContent.primaryText}",
                "secondaryText": "${payload.headlineData.textContent.secondaryText}",
                "footerHintText": "${payload.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

Last updated: Nov 28, 2023