Tutorial: Offer a Custom Skill in Multiple Languages

You can use the Alexa developer console to build a custom skill and offer it in multiple locales. The primary locale is the language and region you use when you create your skill. The new locale is the language and region you add.

In this tutorial, you create a simple skill in English and adapt it for German users. You can offer your skill in as many new locales as you like, however, provided that the skill type is supported in the locales you choose.

Prerequisites

Before you begin this tutorial, you must have an Alexa-hosted Node.js skill for the primary locale (en-US). This English-language skill serves as the starting point for the German version you build with this tutorial.

Steps to offer a custom skill in multiple languages

To offer a custom skill in a new language, complete the following steps.

  1. Add a new locale
  2. Update the interaction model
  3. Supply sample utterances in the new language
  4. Update the request handlers
  5. Change the skill invocation name
  6. Test your skill
  7. Update the skill metadata for the new language
  8. Prepare your skill to reach multiple locales
  9. Validate your skill

Step 1: Add a new locale

To add a new locale, first you update the language settings for your skill. Support for additional locales makes your skill available to more Alexa users around the world.

To add a locale to your custom skill

  1. Open the Alexa developer console and sign in.
  2. Click the Skills tab.
  3. From your list of skills, select Hello World.
    To create this skill, see Steps to Build a Custom Skill.
  4. On the Build tab, click the arrow next to English (US), and then select Language Settings from the drop-down menu.
  5. Next to the plus sign (+), click Add new language.
  6. Select German (DE), and click Save.

Step 2: Update the interaction model

In this step, you copy the English (US) interaction model and paste it into the JSON editor for the German (DE) interaction model. The interaction model for the new locale lets users interact with your skill in their own language.

To update the interaction model with the new locale

  1. On the Build tab, click CUSTOM > Interaction Model > JSON Editor.
  2. Copy the code in the JSON Editor to save it to your clipboard.
  3. In the left sidebar, click the arrow next to English (US), and select German from the drop-down menu.
  4. Paste the code from your clipboard into the JSON Editor to replace the existing code.
  5. To keep this pasted code as your German interaction model, click Save Model.

Step 3: Supply sample utterances in the new language

In this step, for the German version of your skill, you supply German sample launch phrases, keywords, and sample utterances for the HelloWorldIntent. The launch phrases are shown on the skill's detail card in the Alexa app to help users begin to interact with your skill.

To update your custom intent with German sample utterances

  1. On the Build tab, in the left sidebar, under CUSTOM, click Interaction Model > Intents.
  2. Click HelloWorldIntent.
  3. To the right of each English sample utterance, click the trash can icon, and repeat until you delete all of the English sample utterances.

  4. One by one, enter the following German sample utterances.

    hallo
wie geht's
sag hallo welt
sag hallo
hi
  1. Click Save Model, and then click Build Model.

To add sample launch phrases and keywords in German

  1. On the Distribution tab, confirm that the page is open to the German Store Preview, and if not, click the arrow next to Skill Preview, and choose German.
  2. In the Example Phrase 101 pane, click More.
  3. In boxes 1., 2., and 3., respectively, enter the following lines. 
      Alexa, öffne Hallo Welt.
  Alexa, starte Hallo Welt.
  Alexa, führe Hallo Welt aus.
  4. In the Keywords box, enter Hallo, Grüße, Vorstellen, and Fähigkeiten.
  5. Click Save Model, and then click Build Model.

Step 4: Update the request handlers

In this step, you add locale selection logic to the LaunchRequestHandler and to your intent handlers. This logic lets your skill recognize the locale setting on your user's device, so that the skill can respond in the user's language.

To add a locale selector to the launch request handler

  1. On the Code tab, in the left folder tree, navigate to Skill Code > lambda > index.js.
  2. Within the LaunchRequestHandler object, find the line that begins with const speakOutput.
  3. Replace the entire line with the following code.
  const locale = handlerInput.requestEnvelope.request.locale
  let speakOutput = 'Welcome, you can say Hello or Help. Which would you like to try?';
    if (locale === "de-DE") {
       speakOutput = "Willkommen, du kannst Hallo oder Hilfe sagen. Was möchtest du ausprobieren?"
       }
  1. Your amended LaunchRequestHandler function now looks like the following example.

To update the intent handlers

  1. On the Code tab, find each of the built-in intent handlers listed in the following tabbed table.
  2. Follow the instructions on each tab to adapt the handlers for your new locale.
HelloWorldIntentHandler
  1. In the HelloWorldIntentHandler, replace the const speakOutput line with the following code.
  const locale = handlerInput.requestEnvelope.request.locale
        let speakOutput = "Hello World!";
        if (locale === "de-DE") {
           speakOutput = "Hallo Welt!"
           }
  1. At the top of the page, click Save.
  2. The following example is the final code for the HelloWorldIntentHandler.

HelpIntentHandler
  1. In the HelpIntentHandler, replace the const speakOutput line with the following code.
  const locale = handlerInput.requestEnvelope.request.locale
       let speakOutput = "You can say hello to me. How can I help?";
        if (locale === "de-DE") {
           speakOutput = "Du kannst Hallo sagen. Wie kann ich dir helfen?"
           }
  1. At the top of the page, click Save.
  2. The following example is the final code for the HelpIntentHandler.

CancelAndStopIntentHandler
  1. In the CancelAndStopIntentHandler, replace the const speakOutput line with the following code.
  const locale = handlerInput.requestEnvelope.request.locale
       let speakOutput = "Goodbye!";
        if (locale === "de-DE") {
           speakOutput = "Bis bald!"
           }
  1. At the top of the page, click Save.
  2. The following example is the final code for the CancelAndStopIntentHandler.

FallbackIntentHandler
  1. In the FallbackIntentHandler, replace the const speakOutput line with the following code.
  const locale = handlerInput.requestEnvelope.request.locale
       let speakOutput = "I'm sorry, I don't know that one.";
        if (locale === "de-DE") {
           speakOutput = "Es tut mir leid. Ich weiß es nicht."
           }
  1. At the top of the page, click Save.
  2. The following example is the final code for the FallbackIntentHandler.

IntentReflectorHandler
  1. In the IntentReflectorHandler, replace the const speakOutput line with the following code.
  const locale = handlerInput.requestEnvelope.request.locale
        let speakOutput = "You just triggered $(intentName) intent.";
         if (locale === "de-DE") {
            speakOutput = "Du hast gerade ${intentName} ausgelöst."
            }
  1. At the top of the page, click Save.
  2. The following example is the final code for the IntentReflectorHandler.

ErrorHandler
  1. In the ErrorHandler, replace the const speakOutput line with the following code.
  const locale = handlerInput.requestEnvelope.request.locale
       let speakOutput = "I'm sorry, I had trouble doing what you asked.";
        if (locale === "de-DE") {
           speakOutput = "Ich hatte Probleme zu tun, worum du gebeten hast. Bitte versuche es erneut."
           }
  1. At the top of the page, click Save.
  2. The following example is the final code for the ErrorHandler.

Step 5: Change the skill invocation name

In this step, you give your skill a German invocation name. This lets users open the skill in their own language.

To update the German invocation name

  1. On the Build tab, in the left sidebar, confirm that your skill is open to German.
  2. Under CUSTOM, click Invocations > Skill Invocation Name.
  3. In the Skill Invocation Name box, replace hello world with hallo welt.
  4. Click Save Model.

Step 6: Test your skill

In this step, you review and test example phrases to verify that your skill responds to users as expected. When you adapt a skill for a new locale, it must function smoothly and reliably in the new language and region.

To test your skill in the Alexa Simulator

  1. In the upper-left corner, click the arrow next to Off, and select Development from the drop-down menu.
  2. On the Test tab, in the Alexa Simulator, confirm that German is selected.

  3. Enter the first German launch phrase you wrote in Step 3, but omit Alexa, from the string.

    Öffne Hallo Welt.

    Alexa responds with the following greeting.

    Alexa: Willkommen, du kannst Hallo oder Hilfe sagen. Was möchtest du ausprobieren?

  4. One by one, enter the other two launch phrases without Alexa, to make sure you get the same result.

    Starte Hallo Welt.
    Führe Hallo Welt aus.

  5. One by one, enter the three test words listed in the following table.
    If Alexa doesn't respond as expected, see Troubleshooting.
Intent Test word Expected response

HelloWorldIntent

hallo

Alexa: Hallo Welt!

CancelAndStopIntent

cancel

Alexa: Bis bald!

HelpIntent

hilfe

Alexa: Du kannst mir Hallo sagen. Wie kann ich dir helfen?

To check the interaction model for utterance conflicts

  1. On the Build tab, in the left sidebar, under CUSTOM, click Interaction Model > Utterance Conflicts (0).
  2. If any number other than (0) appears next to the term Utterance Conflicts, click to see the details.
  3. Resolve the conflicts, and then press Ctrl+R to refresh your browser window.
  4. Repeat until you see Utterance Conflicts (0).

Step 7: Update the skill metadata for the new language

In this step, you replace the English-language metatdata with German-language details. Automated systems use metadata to categorize your skill and help interested users find your content.

To add metadata for the German version of your skill

  1. On the Distribution tab, confirm that the page is open to the German Store Preview, and if not, click the arrow next to Skill Preview, and choose German.
  2. In the Public Name box, enter Hallo Welt.
  3. In the One Sentence Description box, enter "Hallo Welt" ist der perfekte Weg, für Softwareentwickler ihren ersten Alexa Skill auszuprobieren.
  4. In the Detailed Description box, enter "Hallo Welt" ist eine klassische Skill, Benutzer mit den text-to-speech Möglichkeiten von Alexa bekannt machen.
  5. Leave the What's New box blank.
  6. In the Category box, select Social > Communication.
  7. Click Save and continue.

Step 8: Prepare your skill to reach multiple locales

In this step, you categorize your skill, determine how it looks in the Alexa Skills store, and then make the skill available to the new locale. These steps are included here to illustrate the complete skill creation process, but the skill you build with this tutorial is for demonstration purposes only.

To complete the privacy, terms, compliance, and availability information

  1. Leave the Privacy Policy URL box blank.
    A privacy policy is optional unless your skill links to users' accounts or collects user information. This skill does not.
  2. Leave the Terms of Use URL box blank.
    A terms of use policy is optional. If you do offer such a policy, however, you must supply it separately for each locale.
  3. Click Save and continue.
  4. On the Privacy & Compliance page, answer No to all four questions.
  5. Select the Export Compliance checkbox.

  6. In the Testing Instructions box, enter the following lines.

    Systemanforderungen: Keine
    Testanweisungen: Zum starten, sag "Alexa, öffne Hallo Welt."

  7. Click Save and continue.
  8. On the Availability page, accept the default options, and then click Save and continue.
  9. On the Code tab, click Deploy.

Step 9: Validate your skill

In this step, you run automated validation tests. These tests ensure that your skill complies with legal, privacy, and security requirements for certification.

The skill you build in this tutorial in ineligible for submission as a publicly available skill. You can, however, use this Hello World skill as your starting point to develop a feature-rich, monetizable Alexa skill. If you do so, your skill must pass the validation tests described here.

To run automated validation tests

  1. On the Certification tab, in the left sidebar, click Validation > Run.
  2. Address any validation tests that fail.
    For example, you might need to return to the Privacy & Compliance page to select a checkbox you overlooked.
  3. If your skill fails validation the first time, click Run again.
  4. Repeat this procedure until your skill passes all validation tests.
  5. In the left sidebar, click Submission, and then select Certify now and publish later.
  6. If you like, enter a version message for your own use.
    If you do add a message, you can find it later from the Version History link in the sidebar.

FAQ

The following frequently asked questions (FAQ) section answers your most common questions about this tutorial and the process of skill creation for multiple languages.

Q: Can I monetize an Alexa skill?

The skill you build in this tutorial is not monetizable. You can, however, use this tutorial as a starting point to build a more robust Alexa custom skill. Then you can configure in-skill purchasing or a paid skill.

Q: Where can I get more sample code for multi-language skills?

You can view, fork, or clone Alexa repos that show you how to integrate multiple languages into your custom skill code.

  1. Browse the repos for skill samples.
  2. Search by locale code, such as de-DE, or create a Boolean search for multiple languages, such as en-US AND de-DE.
  3. Search the Alexa organization for custom skill or skill sample.
  4. Use the language filter to target your search results by programming language, such as Node.js.
Q: How do I know if the language I want to add is supported for my use case?

Before you begin development, verify language support for each locale in which you plan to distribute your skill.

Q: Can I use multiple locales with Alexa Conversations Description Language (ACDL)?

Yes. To add supported locales to your ACDL skill, you must update the skill manifest, add an interaction model for each locale, annotate your utterance sets, responses, dialogs, and samples, and deploy to each locale.

Q: How do I add locales of the same language to my skill?

An easy way to extend your skill's distribution is to offer it in other countries where your primary skill language is spoken. English, for example, is spoken not just in the United States (en-US), but also in Australia (en-AU), Canada (en-CA), India (en-IN), and the United Kingdom (en-GB). To add these other supported locales, you can sync your skill, clone it, or automate its distribution. For details, click the following tabs.

Sync Locales

The sync locales feature lets you automatically duplicate custom skill assets for additional locales of the same language.

Clone a locale

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

Automated locale distribution

If your skill is eligible and you opt in, your can distribute your skill to all available locales for a given language.

Q: Should I distribute my skill to all countries and regions, or only to specified locales?

Distribute your skill to all countries and regions if the factors listed in the following "Do" column are important to you. Don't distribute to all locales if the considerations shown in the following "Don't" column are of concern.

Do

You want the largest possible user base.

You want to make your skill available worldwide to users whose devices use a language that your skill supports.

Your skill is broadly relevant. For example, a nutrition facts skill is useful regardless of the user's locale.

Don't

You want to limit skill availability to a given country or region.

Your want to make your skill available worldwide to users whose devices use a language that your skill supports.

Your skill is unlikely to appeal to a geographically broad user base. A skill that locates campsites in the U.S. and Canada, for example, is of little relevance to users in other locales.

Troubleshooting

Issue: The skill responds in the new language but fails to open

Symptoms

In the Alexa Simulator, you receive an error message similar to the following examples.

Alexa: Da bin ich mir leider nicht sicher.
Alexa: Ich bin mir leider nicht sicher.

In other words, "Unfortunately, I'm not sure about that."

Try this

  1. On the Test tab, refresh your browser window.
  2. Select German (DE), not English (US).
  3. On the Build tab, click Interaction Model.
  4. Click JSON Editor > Save Model > Build Model.
  5. Wait for the model to build, and then, on the Code tab, click Deploy.
  6. On the Test tab, in the Alexa Simulator, try your test again with a German launch phrase, such as Öffne Hallo Welt.

Issue: The skill won't open in the new language, and an "audio only" error appears

Symptoms

In the Alexa Simulator, you recieve a message like <Audio only response>.

Try this

  1. On the Build tab, click Interaction Model.

  2. On the JSON Editor page, with German selected, make sure your code contains the following HelloWorldIntent and sample utterances.

    {
   "name": "HelloWorldIntent",
   "slots": [],
   "samples": [
      "hallo",
      "wie geht's",
      "sag hallo welt",
      "sag hallo",
      "hi",
               ]
},
  3. Add the preceding code to your interaction model, if necessary.
  4. Save, build, and deploy your skill again.

Issue: Skill won't open in the new language, and a general error message appears

Symptoms

In the Alexa Simulator, you receive a message indicating that there was a problem with the requested skill.

Alexa: Bei der Antwort des angeforderten Skill ist ein Problem aufgetreten.

Try this

  1. On the Build tab, in the left sidebar, under CUSTOM, click Interaction Model > Intents.
  2. Make sure your interaction model has at least one custom intent (HelloWorldIntent).
  3. Make sure your HelloWorldIntent has a set of sample utterances in German.
    For details, see Step 3: Supply sample utterances in the new language.
  4. Save, build, and deploy your skill again.
Was this page helpful?

Last updated: May 01, 2024