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.

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 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
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
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 the default fonts and left-to-right layout
AlexaButton and AlexaFooter using Arabic-specific fonts and the right-to-left layout
AlexaButton and AlexaFooter using Arabic-specific fonts and the right-to-left layout

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.

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 'LTR' and lang is 'en-US'
Result when layoutDirection is 'RTL' and lang is 'ar-SA'
Result when layoutDirection is 'RTL' and lang is 'ar-SA'

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.

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 'LTR' and lang is 'en-US'
AlexaHeadline template when layoutDirection is 'RTL' and lang is 'ar-SA'
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?

Last updated: Nov 28, 2023