Distribute Your Skill to Additional Locales of the Same Language

To reach more customers, you can expand the distribution of your skill to more locales using automated locale distribution. For example, if you support English (US), automated locale distribution enables your skill to support additional locales like English (UK) and English (India). For custom skills, as part of your skill submission you can opt in to have us assess whether your skill is eligible for automated locale distribution and for which locales.

What is a locale

A locale is the combination of a language and a location. For example, fr-CA is a locale representing the French language spoken in Canada.

Automated locale distribution supports the following locales:

  • English (US), English (UK), English (India), English (Canada), English (Australia)
  • French (France), French (Canada)
  • Spanish (Spain), Spanish (Mexico), Spanish (US)

How automated locale distribution works

When you opt in, we assess whether your skill is eligible for distribution to all locales of a given language.

If you want to further control the distribution of your skill, you can specify the countries to make your skill available in. Otherwise, we will default to distributing the skill to all countries for the given language. For information about specifying countries, see Select Countries and Regions for the Skill.

We do not distribute your skill to additional languages. For example, we will not distribute an en-US skill to countries that do not support English, for example France.

Make sure to update your privacy policy and terms of use for your skill to meet the requirements for all countries and regions where your skill will be available.

Opt in to automated locale distribution

You can use the developer console, ASK CLI, or SMAPI to opt in to automated locale distribution.

For details about using the developer console to opt in to automated locale distribution, see Define Skill Store Details and Availability.

To use ASK CLI or SMAPI to opt in to automated locale distribution

  1. In the skill manifest, under SkillManifest_PublishingInformation specify the automaticDistribution object. The automaticDistribution object is optional. If you specify the object, provide all of the following parameters:

    Field Description Type
    isActive If true, indicates that you want us to distribute your skill in all locales for all languages that your skill supports. If you later set this value to false, the updated setting does not revert any locales to which we previously distributed your skill. boolean
    sourceLocaleForLanguages List of items pairing a language with a source locale. Required if isActive is true. For each language that your skill supports, you must use this array to specify which locale to use as the source for the language. There cannot be more than one instance of the same language in the array. array
    language In the sourceLocaleForLanguages array, two-letter string representing the language to which to distribute the skill, for example en. string
    sourceLocale In the sourceLocaleForLanguages array, locale from where to copy the metadata and model, for example en-US. The locale must already exist in the skill. string
  2. Use ASK CLI or SMAPI to deploy your skill.
  3. Use ASK CLI or SMAPI to resubmit your skill.

Example

Let's say that you specify the countries US, France, and Australia for distribution of your skill, and you create en-US and fr-FR variants of the skill. Then, you opt in by updating the skill manifest as follows:

"automaticDistribution": {
    "isActive": true,
    "sourceLocaleForLanguages": [
     {
        "language": "en",
        "sourceLocale": "en-US"
     },
     {
        "language": "fr",
        "sourceLocale": "fr-FR"
     }
    ]
   },

We evaluate whether the skill is eligible for distribution. Let's say that the skill is eligible for the en-CA, en-IN, fr-CA and en-AU locales. We will expand the distribution of your skill to add only en-AU, because you indicated that the skill can only be distributed to the US, France, and Australia.

Additional examples

The following example is for an English-language skill where you specified all countries and regions, and you created your skill for en-US. The example shows how to distribute the skill to all English-speaking locales and use en-US as the source locale for the distribution.

"automaticDistribution": {
  "isActive": true,
  "sourceLocaleForLanguages": [
    {
      "language": "en",
      "sourceLocale": "en-US"
    }       
  ]      
  },

The following example is for an English-language and French-language skill. The example shows how to specify that you want to distribute your skill to all English-speaking locales using en-US as the source locale, and also distribute your skill to all French-speaking locales using fr-FR as the source locale.

"automaticDistribution": {
    "isActive": true,
    "sourceLocaleForLanguages": [
     {
        "language": "en",
        "sourceLocale": "en-US"
     },
     {
        "language": "fr",
        "sourceLocale": "fr-FR"
     }
    ]
   },

The following example shows how you might expand the distribution of a skill that has already implemented the locales en-US, en-CA, es-US, fr-FR, and it-IT. The example uses en-US as the source locale for English. You might alternatively specify en-CA as the source locale.

"automaticDistribution": {
    "isActive": true,
    "sourceLocaleForLanguages": [
     {
        "language": "en",
        "sourceLocale": "en-US"
      },
      {
        "language": "es",
        "sourceLocale": "es-US"
      },
      {
        "language": "fr",
        "sourceLocale": "fr-FR"
      },
      {
        "language": "it",
        "sourceLocale": "it-IT"
      }
    ]
   },

Frequently asked questions

1. What is a source locale?

A source locale is the locale for which you developed your skill that you want us to use as the basis for distributing the skill to other locales. If you opt in, we make copies of the source locale and distribute it to locales of the same language.

2. What will happen to my skill as part of distribution?

If your skill is eligible, we create variants of your existing skill by copying all skill details, endpoint information, publishing information, and intent schema, and then we publish the skill to customers in the target locales.

3. Is this distribution going to create a new skill in the target language?

We will not create a new skill in the target language. We will add a variant to your existing skill.

4. What makes a skill eligible?

Only custom skills are eligible for automated locale distribution. To prepare your skill for automated locale distribution, make sure that the target locales are not in development stage, that the voice interaction model for the source locale is valid for each destination locale, and that you have not restricted your skill from being available in the target geographical locations. Some features are not eligible for automated locale distribution, for example account linking, in-skill products, and CanFulfillIntentRequest. Some countries and regions may have more restrictive standards for what qualifies as offensive or non-compliant content. We may restrict a skill from being published in any country or region where distribution of the content would violate that country's or region's laws, cultural norms, or sensitivities.

In all cases, skills must also pass Amazon’s certification process, including adhering to Amazon’s content guidelines for all locales in which they are distributed. For more information, see Policy Testing.

5. Why are we not distributing custom skills that use account linking?

We are not distributing custom skills that use account linking because we believe that developers of those skills would want to provide a more localized or custom experience for customers in the target locale, and will manually distribute their skills as necessary.

6. Why are we not distributing smart home skills?

We are not distributing smart home skills because the skills implement account linking. We also believe that developers of smart home skills would want to provide a tailored experience in the target locale for their respective customers.

7. Is distribution required?

Distribution is optional. You can opt in to have us distribute your skill on your behalf by following the steps to update the skill manifest.

8. Are there any technical reasons or considerations to avoid opting in?

One reason you might not opt in is if your skill endpoint is unable to support increased traffic as customers interact with your skill in the target locale. Also, if your skill endpoint checks for existing live locale attribute values at runtime before providing responses, your skill might not work as intended when the runtime locale is set to the target locale. For example, the endpoint logic might check for fr-FR, while the skill has been distributed to fr-CA. Instead of having us distribute the skill, you might manually create a variant of your skill for the target locale and update your skill endpoint.

9. Will the distribution have an adverse effect on the existing live skill?

Distribution will not affect the existing live version of your skill.

10. Do I have to do anything to my existing skill endpoint to support the distribution?

We will use your existing endpoint when creating variants of your skill for the target locales. If you are considering opting in, make sure that your skill endpoint can support an increase in traffic as customers interact with your skill in multiple locales.

11. What if I manually create a variant of my skill prior to the distribution?

If you manually add a variant to your skill for a target locale while we attempt to distribute your skill, your newly added variant will be overwritten during the distribution.

12. After the distribution, can I update the variant of my skill for the target locale?

Once we have finished distributing your skill, you can continue making updates to the variants of your skill and submit your multi-locale skill for certification. For the newly added locales, we recommend optimizing the sample utterances in the intent schema for your skill to enhance the experience for customers interacting with your skill.

13. Will distribution affect the development version of my primary locale?

We will not make any changes to the development version for your primary locale.

14. What will be the state of my skill after distribution has been completed?

Once we have distributed your skill, the live and development versions of your skill continue to exist as is. As part of the distribution, we will create live and development versions of the skill variant based on the information from the existing live version of your skill.

15. Will I be able to suppress or remove only the additionally distributed locale?

You cannot suppress individual locales. For information about suppressing a live skill, see Hide or remove a skill (skill suppression).

16. When I update my live skill, do my changes automatically propagate to additional locales created by automatic locale distribution?

No, changes to your live skill don't automatically propagate to additional locales created by automatic locale distribution. This means that changes made in your source locale aren't automatically applied to your additional locales. When you update a live skill, you must also manually update your locales with your desired changes and then resubmit your skill for certification. This includes updating any locales that were previously added by automated locale distribution.