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

  • You want to avoid manually cloning your locales to keep them in sync.
  • You want to make continuous updates to your skill with changes that are applicable to all locales of the same language.
  • You don't have to make specific locale changes or redevelop your locale.

Your skill must meet the following criteria:

  • Only custom skills are eligible.
  • You have opted-in to use the feature.
  • Your skill has a valid manifest.
  • Your skill isn't a Multi-Capability Skill (MCS).
  • Your skill doesn't use Alexa Conversations.
  • Your skill doesn't use Alexa Blueprints.

Locale clone

  • You want to clone your locales manually to keep them in sync.
  • You want to make continuous updates to your skill with changes that are applicable to all locales of the same language.
  • You don't have to make specific locale changes or redevelop your locale.

Your skill must meet the following criteria:

  • Only custom skills are eligible.
  • Your skill has a valid manifest.
  • Your skill isn't a Multi-Capability Skill (MCS).
  • Your skill doesn't use Alexa Conversations.
  • Your skill doesn't use Alexa Blueprints.

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.

Sync locales

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

  1. Sign in to the Alexa developer console.
  2. Click Create skill.
  3. Choose a skill name.
  4. Under the Primary locale heading, choose your primary language.
  5. To enable sync locales for the language, turn the Sync Locales toggle on.
  6. Finish choosing the remaining options to configure your skill as needed.
  7. Click Create skill.

To enable sync locales for an existing skill

  1. Sign in to the Alexa developer console.
  2. 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.
  3. In the top-left corner, from the drop-down menu, select Language Settings.
  4. In the list of languages, expand the section that contains the language you're configuring, for example, English.
  5. To enable sync locales for the language, turn the Sync Locales toggle on.
  6. Repeat steps four and five for any additional languages you want.
  7. Click Save.

    Your primary and secondary locales sync automatically each time you click Save.

To disable sync locales on an existing skill

  1. Sign in to the Alexa developer console.
  2. 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.
  3. In the top-left corner, from the drop-down menu, select Language Settings.
  4. In the list of language, expand the section that contains the language you are configuring, for example, English.
  5. To disable sync locales for the language, turn the Sync Locales toggle off.
  6. Repeat steps four and five for any additional languages required.
  7. Click Save.

    Your primary and secondary locales sync automatically each time you click Save.

Sync locales statuses

After Sync Locales starts, you receive one of the following notification statuses at the bottom of the screen in the developer console:

  • Sync Locales Started – The sync locales process started.
  • Sync Locales Successful – The sync locales process was successful.
  • Sync Locales 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 See language setting page for more details link provided in the notification.
  • Sync Locales Failed – The sync locales process failed. For more details about how to fix this issue, click the See language setting page for more details link provided in the notification.
Locale clone

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

  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 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.

  6. From the list of the secondary 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.

Automated locale distribution

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 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 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 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 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