Develop Skills in Multiple Languages

You can use the Alexa Skills Kit to create custom skills in multiple languages. A custom skill can support a single language, or any combination of the following available languages:

  • English (AU)
  • English (CA)
  • English (IN)
  • English (UK)
  • English (US)
  • French (CA)
  • French (FR)
  • German (DE)
  • Hindi (IN)
  • Italian (IT)
  • Japanese (JP)
  • Portuguese (BR)
  • Spanish (ES)
  • Spanish (MX)
  • Spanish (US)

Customers who interact with Alexa in a particular language can use skills that support that language. For example, a customer might set their Alexa device to use German. That customer can enable and use any published skills that support German that are available in the Alexa Skills Store in their country or region.

High-level steps to develop multiple-language skills

These instructions cover multiple-language custom skills. For details about these steps, see the following sections.

  1. Design a voice user interface for the language you want to support. The voice user interface includes the following items:
    • Skill invocation name
    • Intent schema
    • Sample utterances
    • Custom slot type values

    For details, see the section Design the voice user interface for each language your skill supports.

  2. Include logic in your code to check incoming requests (IntentRequest, LaunchRequest, and SessionEndedRequest) for the customer's language and respond in the correct language. For example, if the customer launched your skill in German, your skill should return German text-to-speech content that Alexa can speak to the customer.

    For details, see section Implement code changes.

  3. Deploy your updated code to the relevant endpoints:
    • You can use multiple endpoints: North America, Europe and India, and Far East.
    • If you choose to deploy your code to multiple endpoints, you must maintain the same code at all endpoints. The code must handle all languages you support, as noted in the previous step.

    For details, see the section Provide multiple endpoints for your skill.

  4. Configure the skill in the developer console with the new endpoints, the new voice user interface, and other language-specific information.

    For details, see the section Update the skill configuration with language-specific details.

  5. Test the new language version of your skill.

    For details, see the separate topic Test Your Skill.

  6. Configure the distribution for your skill to make it available to customers in relevant locations.

    For details, see the section Decide where to distribute your skill.

Language-specific and global information in the Developer Console

The configuration for a skill in the developer console provides the Alexa service with the information needed to perform the following actions:

  • Route requests to the AWS Lambda function or web service that implements the skill. AWS Lambda is a service offering by Amazon Web Services.
  • Display information about the skill in the Amazon Alexa App.

When you add multiple languages to a skill, some of the information in the configuration applies to all languages, while some applies only to a single language.

  • All aspects of the interaction model (intents, utterances, etc.) are unique to the language.
  • Fields used to present data to the customer in the Alexa App (public name, description, etc.) are unique to the language.
  • Configuration settings such as interfaces, endpoints, account linking settings, and permissions apply across all languages.

Design the voice UI for each language your custom skill supports

For each language that your custom skill supports, you create a voice user interface (UI). This voice UI includes the following items:

  • Invocation name – A phrase that users speak to begin interacting with your skill.
  • Intent schema – A set of intents that your service can accept and process. Consider keeping the intents consistent across different languages so that users have a consistent experience across languages.
  • Sample utterances – A mapping between the intents and likely spoken phrases.
  • Custom slot type values – A representative list of values defined for each custom slot type in your intent schema.

For details about these items, see the following topics:

When you choose your invocation name and write sample utterances, make sure to use words and phrases appropriate for native speakers of the language.

For details about setting up a new language and adding a language-specific voice UI, see Update the skill configuration with language-specific details, later in this topic.

Implement code changes for a custom skill

Create your cloud-based service for your skill so that it can handle requests from all languages you support. For example, if your skill supports both German and English (UK), the same code must perform the following actions:

  • Take a German request and respond to the user with German text-to-speech responses.
  • Take an English (UK) request and respond to the user with English text-to-speech responses.

You can determine the language used to invoke the skill by checking the locale property included in all requests sent to your service (for example, LaunchRequest or IntentRequest). For details about the different types of requests your skill can receive, see Request Format.

The following example shows the locale property en-US as part of the request object.

{
  "request": {
    "type": "LaunchRequest",
    "requestId": "EdwRequestId.00000000-0000-0000-0000-000000000000",
    "timestamp": "2016-06-14T20:59:24Z",
    "locale": "en-US"
  }
}

The following table shows the locale property locale-code and language options.

Locale code Language

de-DE

German (DE)

en-AU

English (AU)

en-CA

English (CA)

en-GB

English (UK)

en-IN

English (IN)

en-US

English (US)

es-ES

Spanish (ES)

es-MX

Spanish (MX)

es-US

Spanish (US)

fr-CA

French (CA)

fr-FR

French (FR)

hi-IN

Hindi (IN)

it-IT

Italian (IT)

ja-JP

Japanese (JP)

pt-BR

Portuguese (BR)

Although Amazon doesn't require feature parity across languages, customers can choose the language for their devices and switch between languages. Therefore, a customer might interact with your skill in more than one language, so providing a consistent experience across languages is important.

Provide multiple endpoints for your skill

The Alexa service currently determines which endpoint to call based on the customer's location and the endpoints you provide. You can specify any combination of the following endpoints for your skill.

Geographical region Used for...

North America

Customers in North America (customers who registered their device with the .com, .ca, or .com.br site)

Europe and India

  • Customers in Europe (customers who registered their device with a European site, such as .de, .fr, or .co.uk)
  • Customers in India (customers who registered their device with the India site .in)

Far East

Customers in Japan and Australia/New Zealand (customers who registered their device with .co.jp or .com.au)

If the preferred endpoint for the customer's region isn't available, Alexa calls the default endpoint.

If you choose to use multiple endpoints, you must deploy the same code to each one. The Alexa service can send a customer request in a particular language to any of your endpoints. For example, suppose that your skill supports both English (US) and German. An English request from a customer using amazon.de would go to the Europe endpoint (if provided). The code at that endpoint must be able to handle and respond appropriately to an English-language request. Use the locale property provided in the request to identify the customer's language, as described in Implement code changes for a custom skill, earlier in this topic.

If you use AWS Lambda to host your skill service, determine which of the allowed AWS Lambda regions is best for your skill configuration. For details, see Select the optimal region for your AWS Lambda function.

Update the skill configuration with language-specific details

To add support for additional languages, you must add the language to the skill configuration and provide the language-specific information, such as your new voice user interface.

To add a language to an existing skill

  1. Go to developer.amazon.com/alexa.
  2. Click Your Alexa Consoles, and then click Skills.

    The developer console opens and displays any skills you have already created.

  3. From the list, find the custom skill that you want to add a language to, and then click Edit.
  4. In the upper-left, click the language drop-down menu, and then click Language Settings.

    The Language Settings page lists all the languages already included in your skill.

  5. Click Add new language, choose the language to add, and then click Save.

After you've added at least one additional language to a skill, you can switch between languages with the language drop-down menu.

To update the skill with language-specific details

  1. From the language drop-down menu, select the language you want to edit.
  2. On the Build page, complete the sections under Custom.
    • In the Interaction Model section, add your language-specific interaction model.
    • If necessary, add your additional endpoints in Endpoint.
  3. On the Distribution page, Under Skill Preview, select the language, and then fill in the fields to display the skill in the Alexa Skills Store.
  4. In the Availability section, select where you want to distribute your skill.

Clone a skill locale

To speed up your development, you can clone existing locale assets of a custom skill and reuse them. After cloning the assets, you use them as a starting point to configure a new locale in the same language.

For example, if you have already built a custom skill with the en-US locale, you can use the skill locale clone feature to extend that locale asset to another locale in the same language, such as en-CA. This process creates a copy of your skill's manifest data and interaction model. The clone also copies the invocation name, API usage—such as Alexa Presentation Language (APL) or Account Linking—and endpoint URL. The skill locale clone feature supports all languages. However, the feature doesn’t support cross-language locale cloning. For example, you can't clone a skill from en-US to es-ES, but you can clone a locale from en-US to en-GB.

In addition, skill locale cloning only clones a source locale to an existing destination if you have selected the Overwrite option in the developer console. By default, this feature doesn't clone locales for existing destination locales. For example, if you already developed a custom skill for both en-US and en-CA, neither of these locales are available to clone. However, you can use the Overwrite option to clone en-US to en-CA or en-CA to en-US. If there's a problem with the Overwrite settings, you receive a validation error. This error typically occurs if the target locale already exists.

You clone locale assets with the developer console – as shown in the following section – or by using the CLI clone-locale subcommand.

Clone a skill locale with the developer console

When you clone a skill locale with the developer console, first you find the existing custom skill that you want to clone, and then you find the source locale that you want to clone.

To clone a skill locale with the developer console

  1. Go to developer.amazon.com/alexa.
  2. Click Your Alexa Consoles, and then click Skills.

    The developer console opens and displays any skills you have already created.

  3. From the list, find the custom skill that you want to clone, and then click to select that skill.
  4. In the top-left corner, from the drop-down menu, select Language Settings.
  5. Find the source locale that you want to clone, and then click Clone.

    The section expands with additional locale information that you must select in the next step.

  6. From the list of the target locales, select the check boxes of the locales that you want to clone.
  7. Click Clone.

    For example, the following screenshot shows how to clone the AU, CA, IN, and UK locales.

  8. If the locale that you try to clone already exists in your skill, a pop-up window asks you for permission to overwrite the existing locale.
    • If you agree, Click Overwrite.
    • If you don't agree, click Cancel.

    The clone locale workflow starts.

  9. Under Clone in progress, view the ongoing progress of the workflow.

    After the clone process finishes, the message Clone successful appears.

Decide where to distribute your skill

The Where would you like this skill to be available? option determines the countries and regions in which your customers can enable and use your custom skill. Your customers can access all skills that meet all of the following conditions:

  • You distribute your skill in the customers' country or region.
  • Your skill supports the language your customers selected for their Alexa-enabled devices.
  • Your skill supports the primary language for the country or region in which the customers registered their devices. This support determines whether the skill is available in the skills store; for example:
    • A skill must have an English (US) version to be available to customers who registered their devices with the .com site.
    • A skill must have a German version to be available to customers who registered their devices with the .de site.

The distribution applies to the skill, not to individual languages. Amazon makes available all language versions of the skill in the specified countries and regions, barring content-policy restrictions.

Example: Worldwide distribution with one language

You choose to distribute your custom skill in all countries and regions where Amazon distributes skills. You configure the skill with just English (UK) and no other languages. When you choose this configuration, you get the following result:

  • Your skill is available in the skills store for all countries and regions where English (UK) is the primary language.
  • Your skill can be used by customers in those countries and regions who have set their devices to use English (UK).
  • Your skill isn't available to customers anywhere in the world who have selected German, English (US), or any other language for their devices.

Example: Limited distribution with multiple languages

You choose to distribute your custom skill only in Germany because your skill's functionality is region-specific. You configure the skill with German and English (UK) for the languages. When you choose this configuration, you get the following result:

  • Your skill is available only in the German skills store, due to the selected country distribution.
  • Your skill can be used by customers in Germany who have set their devices to use German.
  • Your skill can be used by customers in Germany who have set their devices to use English (UK).
  • Your skill can't be used by customers in Germany who have set their devices to use English (US) or any other language.
  • Your skill can't be used by customers in any other country or region, regardless of the language they've selected for their devices.

Should your skill be available everywhere?

You must decide how broadly you want your custom skill available to customers and users. You do this when you choose the In all countries and regions where Amazon distributes skills selection or leave the selection blank. To make this determination, consider your two options:

  • Choose the In all countries and regions where Amazon distributes skills selection if the following factors are important:

    • You want your skill available to customers worldwide who have configured their devices to use a language that your skill supports.
    • You want the largest possible customer and user base.
    • You think your skill can be useful to customers in other countries or regions. For example, a trivia game skill can be entertaining regardless of where the customer might live, especially if you can add additional languages.
  • Don't choose the In all countries and regions where Amazon distributes skills selection if the following factors are important:

    • You want to limit the availability of your skill to a particular country or region.
    • You want your skill available just to customers in the specified country or region who have configured their devices to use a language that your skill supports.
    • You think your skill can be useful to customers only in particular geographic areas. For example, a skill that provides food delivery for major US cities, but not in Europe, wouldn’t be useful in countries or regions other than the United States.