Translating the Interaction Model
As we’ve developed the Star Port 75 Travel skill, we’ve defined the skill’s interaction model—utterances, slots, dialogs, and prompts—in the skill-package/interactionModels/custom/en-US.json file. As implied by its name, that interaction model is specifically for devices configured for U.S. English. Now, as we are ready to expand to other locales and languages, we need to create additional interaction model files.
Alexa does not support all languages or locales. Chinese, for instance, isn’t supported yet, nor are any Chinese locales such as Hong Kong, Taiwan, and Singapore. Nevertheless, Alexa does support nine languages in over a dozen different locales:
- Arabic/Saudi Arabia (ar-SA)
- German/Germany (de-DE)
- English/Australia (en-AU)
- English/Canada (en-CA)
- English/United Kingdom (en-GB)
- English/India (en-IN)
- English/US (en-US)
- Spanish/Spain (es-ES)
- Spanish/Mexico (es-MX)
- Spanish/US (es-US)
- French/Canada (fr-CA)
- French/France (fr-FR)
- Hindi/India (hi-IN)
- Italian/Italy (it-IT)
- Japanese/Japan (ja-JP)
- Portuguese/Brazil (pt-BR)
Supporting additional locales and languages involves creating new interaction model files in the skill-package/interactionModels/custom directory, one for each language-locale pair you wish to support. Each interaction model JSON file will adhere to the same format we used for U.S. English, translating the utterances, prompts, and synonyms to match the language.
Since we already have an interaction model for English-speaking users in the United States, we can quickly add support for all other English-speaking locales by simply copying the en-US.json file to en-AU.json, en-CA.json, en-GB.json, and en-IN.json. We’d only need to change those files if any utterances, prompts, or synonyms are to use any locale-specific colloquialisms.
Alternatively, the ASK CLI offers the ask smapi clone-locale command that can be used to clone a skill’s locales:
| | $ ask smapi clone-locale |
| | --skill-id amzn1.ask.skill.68a3c3b3-63f5-40b0-b1ad-57636ac4067d |
| | --source-locale en-US |
| | --target-locales en-AU,en-CA,en-GB,en-IN |
Locale clones can only be created from an existing locale with the same language. In this case, we are cloning the en-US locale to the other English locales. You can’t, however, clone an English locale into a different language.
Locale cloning is asynchronous, so the command will return immediately, but may take a little longer to complete the cloning process. You can check on the status using the ask smapi get-clone-locale-status command:
| | $ ask smapi get-clone-locale-status |
| | --skill-id amzn1.ask.skill.68a3c3b3-63f5-40b0-b1ad-57636ac4067d |
| | --stage development |
| | --clone-locale-request-id 0d34c78d-7de3-4478-be7e-580338e29b05 |
| | --profile default |
The --clone-locale-request-id parameter required to check the cloning status (as well as the other parameters) are available in the response to the ask smapi clone-locale command.
Once the cloning has completed successfully, you’ll need to fetch the locale-specific interaction model files using ask smapi get-interaction-model. For example, to fetch the interaction model JSON file for “en-GB”, you can use the ASK CLI like this:
| | $ ask smapi get-interaction-model |
| | --skill-id amzn1.ask.skill.68a3c3b3-63f5-40b0-b1ad-57636ac4067d |
| | --locale en-GB > skill-package/interactionModels/custom/en-GB.json |
Although cloning locales using the ASK CLI like this is explicit in its purpose, you’ll probably find it much simpler to just make a copy of the en-US.json file for each of the other locales.
By simply replicating the English interaction model across all English locales, our skill suddenly works with two-thirds of language-locale pairs supported by Alexa. For the others, we can copy the existing model JSON files for each language-locale we want to support, and then edit each JSON file, translating the utterances, prompts, and synonyms to the target language.
In this chapter, we’re going to expand Star Port 75 Travel to three additional locales by creating new interaction model files for each of the three locales that serve Spanish-speaking travelers. You are welcome to add additional language and locale support for other languages if you wish, following the same approach we’ll use for Spanish.
We’ll start by copying the contents of en-US.json to es-ES.json and translating its content to Spanish. Once we’ve finished the translation in es-ES.json, we’ll copy it for the other two Spanish-speaking locales.
After creating es-ES.json from en-US.json, open the es-ES.json file in your text editor. Our first bit of translation work will be with the invocation name. Typically, the invocation name will need to be translated to the target language, unless it is a brand name that is well-recognized without translation. For Star Port 75, we will translate the invocation name to Spanish like this:
| | { "interactionModel": { "languageModel": { |
| » | "invocationName": "puerto estrella setenta y cinco", |
| | ... } |
Next, we’ll need to translate sample utterances in the skill’s intent declarations. The skill’s main intent is ScheduleTripIntent, which when translated to Spanish, looks like this:
| | { "name": "ScheduleTripIntent", "samples": [ "programar un viaje a {destination} dejando {departureDate} y regresando {returnDate}", "planifique un viaje entre {departureDate} y {returnDate} para visitar {destination}", "programar un viaje a {destination}", "planear un viaje entre {departureDate} y {returnDate}" ], "slots": [ { "name": "destination", "type": "PLANETS" }, { "name": "departureDate", "type": "AMAZON.DATE" }, { "name": "returnDate", "type": "AMAZON.DATE" } ] } |
Notice that the intent’s name and the names of its slots don’t need to be translated. They must remain the same so that the fulfillment code can continue to reference them by those names. But the utterances in the samples property must be changed to match how a Spanish-speaking user may ask to plan a trip. The key is to only change the things that a user may say or hear.
We must also change the values and synonyms of our custom PLANETS type. Here is the PLANETS type with all of its entries translated to Spanish:
| | "types": [ { "name": "PLANETS", "values": [ { "id": "MERCURY", "name": { "value": "Mercurio", "synonyms": [ "el mas cercano al sol", "el planeta veloz" ] } }, { "id": "VENUS", "name": { "value": "Venus", "synonyms": [ "la estrella de la mañana", "la estrella de la tarde" ] } }, { "id": "EARTH", "name": { "value": "Tierra", |
| | "synonyms": [ "el planeta azul", "el gran mármol azul", "la tercera roca del sol" ] } }, { "id": "MARS", "name": { "value": "Marte", "synonyms": [ "el planeta rojo" ] } }, { "id": "JUPITER", "name": { "value": "Júpiter", "synonyms": [ "el Grande", "el planeta gigante", "el que tiene un ojo" ] } }, { "id": "SATURN", "name": { "value": "Saturno", "synonyms": [ "el planeta anillado" ] } }, { "id": "URANUS", "name": { "value": "Urano", "synonyms": [ "el gigante de hielo" ] } }, { "id": "NEPTUNE", "name": { "value": "Neptuno", |
| | "synonyms": [ "el planeta azul" ] } }, { "id": "PLUTO", "name": { "value": "Plutón", "synonyms": [ "el planeta enano" ] } } ] } ] |
The type’s name and each entry’s id property must remain untranslated. But the name and synonyms are things that a user may say in the destination slot when planning a trip, so those must be translated.
There’s one more bit of translation needed in the interaction model. The dialogs section doesn’t include anything a user may say or hear; no translation is required. But the prompts section contains mostly things a user may hear, so we’ll definitely need to translate all of those prompts.
For now, let’s focus on the prompts that elicit values for the destination, departure date, and return date slots. Here are the elicitation prompts, with each of their variations translated to Spanish:
| | "prompts": [ { "id": "Slot.Elicitation.ScheduleTrip.Destination", "variations": [ { "type": "PlainText", "value": "¿A donde quieres ir?" }, { "type": "PlainText", "value": "¿Qué planeta te gustaría visitar?" } ] }, { "id": "Slot.Elicitation.ScheduleTrip.DepartureDate", |
| | "variations": [ { "type": "PlainText", "value": "¿Cuándo quieres partir?" }, { "type": "PlainText", "value": "¿Cuándo comenzará tu viaje?" } ] }, { "id": "Slot.Elicitation.ScheduleTrip.ReturnDate", "variations": [ { "type": "PlainText", "value": "¿Cuándo quieres volver?" }, { "type": "PlainText", "value": "¿Cuándo terminará tu viaje?" } ] }, ... ] |
As with the other elements of the interaction model, we only need to translate the variations of each prompt. We must leave the prompt IDs unchanged, as those are referenced from the dialogs section.
You are welcome to translate the remaining prompts on your own. When finished, we’ll have created a Spanish translation of the interaction model for the Spain locale. By copying es-ES.json to es-US.json and es-MX.json, we will have fully covered all supported Spanish-speaking locales in our interaction model.
But the interaction model is only half of the translation work. We also must translate the messages that Alexa speaks in responses from our intent handlers. Let’s turn our attention to the fulfillment implementation to finish the translation work.