Add Additional Locales of the Same Language to Custom Skills
To expand your customer reach, you can add additional locales of the same language to your custom skill. For example, if you support American English (en_US), you can try to reach customers in different regions by adding UK English (en_GB) and India English (en_IN) locales to your custom skill.
The following sections describe the features you can use to add additional locales of the same language to your custom skill. For conceptual information about how to use multiple locales in your custom skill, see Configure a Skill for Multiple Languages.
About adding additional locales of the same language to your custom skills
You can add additional locales of the same language to your custom skills by using one of the following features:
- Sync locales – Automatically duplicates your custom-skill locale assets to additional locales of the same language. When you use this feature, you choose a primary locale and a set of secondary locales. Your locales automatically sync every time you build your primary locale's interaction model or save a manifest change.
- Locale clone – Duplicates your custom-skill locale assets to additional locales of the same language. When you use this feature, you choose a primary locale and a set of secondary locales. Cloning occurs after you explicitly choose the clone option in the developer console. This feature doesn't continuously sync your locales automatically.
- Automated locale distribution – Automatically publishes existing custom-skill locale assets to other preconfigured locales of the same language without the need for certification.
The following table describes when it might be appropriate for you to use each of these features.
Feature | When to use | Eligibility criteria |
---|---|---|
Sync locales |
|
Your skill must meet the following criteria:
|
Locale clone |
|
Your skill must meet the following criteria:
|
Automated locale distribution |
You want to publish existing custom skill locale assets automatically to other preconfigured locales of the same language. |
Your skill must meet the following criteria:
|
How to add additional locales of the same language to your custom skills
Choose one of the following tabs for more details about how to use each of the features described in the previous section.
About sync locales
The sync locales feature automatically triggers every time you build your primary locale's interaction model or save a manifest change. After you complete one of these actions, your secondary locales are then updated with your changes.
Sync locales automatically triggers every time you build your primary locale's interaction model or save a manifest change. After you complete one of these actions, your secondary locales are then updated with your changes.
Use sync locales
You control the sync locales feature with an opt-in toggle that's made available in the developer console on the Language Settings page.
After you opt in, you choose a primary locale and a set of secondary locales from the menu made available in the developer console on the Language Settings page. When the sync locales feature triggers, it automatically copies your primary locale to the secondary locales you have selected.
Sync locales runs in the background so you can continue to make updates to your skill. Due to this, sync locales might overwrite any manual updates that you have made to your secondary locale. If you want to make specific changes to your locale, opt out of the sync locales process. For more details about how to control opt-in and opt-out settings, see Use sync locales.
To enable sync locales for a new skill
- Sign in to the Alexa developer console.
- Click Create skill.
- Choose a skill name.
- Under the Primary locale heading, choose your primary language.
- To enable sync locales for the language, turn the Sync Locales toggle on.
- Finish choosing the remaining options to configure your skill as needed.
- Click Create skill.
To enable sync locales for an existing skill
- Sign in to the Alexa developer console.
- From the list of existing skills, find the custom skill that you want to enable sync locales for, and then click to select that skill.
- In the top-left corner, from the drop-down menu, select Language Settings.
- In the list of languages, expand the section that contains the language you're configuring, for example, English.
- To enable sync locales for the language, turn the Sync Locales toggle on.
- Repeat steps four and five for any additional languages you want.
-
Click Save.
Your primary and secondary locales sync automatically each time you click Save.
To disable sync locales on an existing skill
- Sign in to the Alexa developer console.
- From the list of existing skills, find the custom skill that you want to enable sync locales for, and then click to select that skill.
- In the top-left corner, from the drop-down menu, select Language Settings.
- In the list of language, expand the section that contains the language you are configuring, for example, English.
- To disable sync locales for the language, turn the Sync Locales toggle off.
- Repeat steps four and five for any additional languages required.
-
Click Save.
Your primary and secondary locales sync automatically each time you click Save.
Sync locales notifications
Sync locales notifies you of the results in the notifications center in the developer console. The following notifications are possible. The notification includes a View link to get more detail about the results.
Notification | Details |
---|---|
Sync locales for [Skill name] was successful | |
[Skill name] skill is ineligible for sync locale |
Click the View link to see details. Refer back to the table in About adding additional locales of the same language to your custom skills for more about requirements to use sync locales. |
Sync locales for [Skill name] skill failed |
The sync locales process failed. For more details about how to fix this issue, click the View link provided in the notification. |
Sync locales for [skill name] skill was partially successful |
The sync locales process partially finished. For example, some locales might have cloned successfully, but others didn't. For more details about how to fix this issue, click the View link provided in the notification. |
About locale clone
To speed up your development, you can clone the existing locale assets of a custom skill. After cloning the assets, you use reuse 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 clone your local assets to extend your skill 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, endpoint URL, and specific API usage – such as Alexa Presentation Language (APL) or Account Linking.
You can clone a locale across all languages. However, you can't clone a locale to support cross-language changes. For example, you can clone a locale from en-US
to en-GB
, but you can't clone a skill from en-US
to es-ES
. The cloning process copies over all manifest data and interaction model values as-is, without any regional overrides.
Use locale clone
When you clone a locale with the developer console, first you find the existing custom skill that you want to clone, and then you find the primary locale that you want to clone. You can also use this feature with the equivalent ASK CLI commands or SMAPI APIs.
To use the Locale clone feature with the developer console
- Go to https://developer.amazon.com/alexa/console/ask.
-
Click Skills.
The developer console opens and displays any skills you have already created.
- From the list, find the custom skill that you want to clone, and then click to select that skill.
- In the top-left corner, from the drop-down menu, select Language Settings.
-
Find the primary 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.
- From the list of the secondary locales, select the check boxes of the locales that you want to clone.
-
Click Clone.
For example, the following screenshot shows how to clone the
AU
,CA
,IN
, andUK
locales. - 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.
-
Under Clone in progress, view the ongoing progress of the workflow.
After the clone process finishes, the message Clone successful appears.
Important: For best results, don't navigate away from this page while the clone is in progress. In addition, don't perform any parallel actions on the skill, such as updating the skill or modifying any other skill parameters. If your clone process encounters an error, the developer console displays an error message. Follow the instructions in the error message to help solve your issue.
About automated locale distribution
To use automated locale distribution, you must opt-in first. 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 more details about specifying countries, see Select Countries and Regions for the Skill.
- We don't distribute your skill to additional languages. For example, we won't distribute an
en-US
skill to countries that don't 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.
Use automated locale distribution
You use the developer console, ASK CLI, or SMAPI to opt in to automated locale distribution.
To use the developer console to opt into automated locale distribution
For details about using the developer console to opt in to automated locale distribution, see Define Skill Store Details for Publication.
To use ASK CLI or SMAPI to opt in to automated locale distribution
-
In the skill manifest, under
SkillManifest_PublishingInformation
specify theautomaticDistribution
object. TheautomaticDistribution
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 primary 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 exampleen
.string sourceLocale In the sourceLocaleForLanguages
array, locale from where to copy the metadata and model, for exampleen-US
. The locale must already exist in the skill.string - Use ASK CLI or SMAPI to deploy your skill.
- 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 primary 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 primary locale, and also distribute your skill to all French-speaking locales using fr-FR as the primary 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 primary locale for English. You might alternatively specify en-CA as the primary 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
Sync locales
Automated locale distribution
Related Topics
Last updated: Sep 10, 2024