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
- How automated locale distribution works
- Opt in to automated locale distribution
- Example
- Additional examples
- Frequently asked questions
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.
Opt in to automated locale distribution
To opt in, update the skill manifest and then use ASK CLI or SMAPI to submit the updates. 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 |
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. Are all skills eligible?
We evaluate whether a skill is eligible based on our acceptance criteria. For example, skills that contain account linking are not eligible, nor are smart home skills. 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).
