Developing Smart Home Skills in Multiple Languages
You can use the Smart Home Skill API to create smart home skills that respond to customer requests made in different languages. For a supported language, the Smart Home Skill API automatically interprets the customer request and sends the appropriate directive to code (skill adapter) that can handle the request. The skill adapter communicates with the device cloud and performs the desired request or returns a fault message. The languages supported are:
- English (US)
- English (UK)
If you are using one OAuth provider, you can follow the steps in this document to add a language to an existing skill or to create a skill in multiple languages.
The steps for multi-language support are:
- Create multiple language versions of the skill in the developer portal. The skill’s Application ID is the same across all languages, but the Name can be different across languages
- Deploy your skill adapter for the skill to multiple AWS regions. This helps ensure low latency and provides a unique Amazon Resource Number (ARN) for each region the skill adapter is hosted in.
- Add the ARN number for each AWS region to the skill information in the developer portal
- Whitelist URLs for account linking for each language version of your skill
- Enable, account link and test your skill in multiple languages
- Provide additional configuration and publication details for each language version of your skill in the Developer Portal
Note that this document supplements existing Smart Home Skill API documentation and is specific to multi-language skills. You should understand how the Smart Home Skill API works and how to create a skill adapter.
For more information on the Smart Home Skill API or how to create a smart home skill, see
Create Multiple Language Versions of a Skill in the Developer Portal
To Add a language to an existing English (US) skill:
- Sign in to the developer portal, navigate to your list of skills and select the skill you will add additional language support for.
- Select the Add a New Language tab, and choose either English (UK) or German
- Enter the Name of the skill you’d like to use for this language. You can use different names for different language versions of the same skill Once you add a language to your skill, you will need to provide all of the skill and publishing information, and configuration details for the additional language before you submit it for certification.
To add a new skill that supports one or more languages:
- Sign in to the portal, choose Get Started on Alexa Skills Kit and select Add a New Skill.
- Choose a language from the drop-down (you will add additional languages in a later step), and Smart Home Skill API
- Enter the name for your skill for the language you have chosen. Skills can have different names for each language they are offered in. Click Save
- Choose the Add a New Language Tab and choose another language from the drop-down
- Enter the name for your skill for the language you have chosen
It’s important to note that you cannot submit a multi-language skill for certification until all of the required skill and publishing information and configuration details are complete for each language version of the skill. If you don’t have all of this information, it is better to submit a skill for certification in one language and add additional languages later.
Deploy Your Skill Adapter to Multiple Regions
A skill adapter is code that you write that receives directives from the Smart Home Skill API and communicates with the cloud-connected devices that your skill supports. The Smart Home Skill API interprets a customer request for you whether it’s in German or English, and sends the correct directive to the skill adapter. You deploy the adapter as an AWS Lambda function, and to support multiple languages, you should deploy your smart home skill adapter to multiple AWS regions. This helps ensure your skill is responsive to requests. Alexa sends the directives to an adapter based on the language setting of the user. For example, if a customer has selected German as their language, the Smart Home Skill API knows to send the directive to the adapter you have configured for the German version of your skill.
- Deploy a skill adapter to the EU (Ireland) region for English (UK) and German skills.
- Deploy a skill adapter to the US East region for English (US) skills.
Make a note of the ARN for each region. You will add an ARN for each region in the Developer Portal.
For more detailed steps on how to create a skill adapter, see the Create a Lambda Function section of Steps to Create a Smart Home Skill and for details on the directives that your adapter could receive, see Smart Home Skill API Reference.
Provide the ARN numbers for Your Skill in the Developer Portal
Add the ARN number for each region to the configuration page in the developer portal. To do this:
- In the Developer Portal, select the skill and click a language tab.
- Click the Configuration page.
- Select a region, such as Europe and enter the ARN for the Lambda endpoint in the textbox provided. Enter an ARN for the for EU (Ireland) region for English (UK) and German skills, and the US East region for English (US) skills.
- Note the redirect URL by region. You will need to white-list the additional URLs with your OAuth provider.
Whitelist Additional URLs With Your OAuth Provider
You must provide Account Linking information for every smart home skill. This information is global across different language versions of your skill. However, each Lambda region for a multi-language skill has a different Redirect URL, which is provided on the Configuration page for your skill in the Developer Portal. You must whitelist each of the Redirect URLs with your OAuth provider. You will need this to successfully account-link your skill to a device cloud and test your skill. For more information about Account Linking, see Linking an Alexa User with a User in Your System.
Enable, Account Link and Test Your Skill in Multiple Languages
You should test your skill using an Alexa-enabled device that is registered to the same developer account used to create the skill. You can find your skill by browsing to Skills the Alexa app, and choosing Your Skills in the upper right corner. You will also need cloud-connected devices that your skill is designed to work with that are configured and account-linked to the Alexa-enabled device.
The following table provides a few sample utterances in English and German for testing purposes. Although Alexa provides the language handling for you, you should test your skill in all languages that it supports.
|Intent||Sample English (UK and US)||Sample German|
|discover appliances||Alexa, discover my smart home devices||Alexa, finde meine smarten Geräte|
|turn on device(s)||Alexa, turn on the device name||Alexa, schalte Gerätename ein|
|set a device to a value||Alexa, set the room name to number degrees||Alexa, stelle Raumname auf Anzahl Grad|
For more example utterances, see the Smart Home Skill API Reference topic.
Provide Testing Instructions and Choose the Distribution for Your Skill
The final steps to publishing your skill are to provide test instructions for the certification team, choose where you will distribute your skill and provide descriptive information that displays to the customer in the Alexa app.
This page contains a mix of global and language specific fields. Testing Instructions and Distribution are global across language versions. Global fields are located in the gray box at the top of the page. When you answer questions that apply globally, a Save Global changes dialog appears that confirms the change before you move to the next page.
For Testing Instructions:
- Provide contact information and test account credentials for account linking.
Choose the SELECT ALL option to distribute your skill in all countries where Amazon distributes skills. The distribution is independent of language – a skill can be available in a particular country even if it does not support languages commonly spoken in that country.
Note that this option applies to all language versions of your skill. Once international support for Alexa is launched publicly, customers will be able to access all skills that meet both of the following:
The skill is distributed in their country or region.
The skill supports the language selected for their Alexa-enabled device.
Because a smart home skill relies on cloud-connected devices, you should consider whether the devices that accompany your skill are available to customers and will function correctly in a particular country/region.
Provide Publishing Information for Your Skill
The publishing information is not global, and must be completed for each language version of your skill. Following is an example of the Publishing Information page from the developer portal.
Select a language tab to provide values for the following fields. To pass certification, values for these fields must be provided in the same language the skill is offered in.
- Short Skill Description
- Full Skill Description
- Small and Large Icons
Each field contains detailed instructions. When you’ve completed these items, click Next to move to the next page.
Answer the Privacy and Compliance Questions
Submit Your Skill for Certification
When you have completed all of the requested information for each language version of your skill, the Submit for Certification button will be enabled, and you can submit the skill for certification.
To help the certification team, you should respond to any requests for more information promptly.