Localize your Actions

Since Actions provide a conversational interface, there are more things to consider when localizing an Actions project than an average development project. Many components of your Action require translation, including settings, resources, intents, types, and prompts.

Some components of an Action require particular attention to ensure that the conversational interface works in the target language. For example, training phrases used to invoke intents should be created in consultation with native speakers of the target language, rather than simply translating the phrases created in the default language into the target language.

Actions Builder and the Actions SDK both support localization of your Action. When localizing an Actions project, there are two distinct groups of entities that require localization: project settings/resources and conversational components.

Project settings and resources

A project's settings include the information users find in your Action's directory listing, like short and long descriptions of your Action's functionality.

Resources are images, audio files, and other project strings that require localization, like logo images or recorded audio used in prompts.

Localizing a project's settings and resources is just a matter of providing translated versions of the settings/resources from the original locale to the new locale.

Conversational components

Localizing conversational components is different than just providing a translation of existing content. The main objective of localizing a conversation for other locales is to provide a conversational experience that feels natural and intuitive; a concept that varies based on the specific context of the locale language and its evolution.

The following sections discuss considerations for localizing intents, types, and prompts in your Actions project.

Intents

Intents express a user's desire or need that your Action can fulfill. Training phrases you provide in an intent help the Assistant's Natural Language Understanding (NLU) determine which of the Action's intents match what a user is requesting.

When you localize training phrases for an intent, instead of just translating the existing phrases, you should consider the meaning of the intent and define training phrases that better express potential user requests in the target language. The expressivity of languages varies based on how the local context has affected the evolution of the language, and the range of expressions available to define concepts.

As an example, consider a conversational interaction where you ask users to identify something they consider lucky. In Brazil, this could be having a pot of salt in the corner of a room. In Japan, a user who sees a spider in the morning is lucky. In China, a user who sees the number 8 or the color red may consider themselves lucky.

Types

Types are used to define entities that your business logic needs to handle. For example, options and modifications to items a user is ordering. Synonyms for type values make the Assistant NLU more effective at extracting information from what a user says. Even a simple yes type value should have synonyms like yeah or okay, as a user might use a different word for affirmation.

When localizing synonyms for type values, it's important to consider different languages can have a varying number of synonyms for the same concept, depending on factors like the evolution of the local language and culture.

An example that helps clarify this is the concept of snow. In English, there are a handful of words for snow, including flurry, blizzard, slush, and powder. In contrast, the Sámi family of languages spoken in Northern Europe, has well over 100 words for snow.

There are two points that you should consider when localizing a hypothetical type, like snow:

  • Variety of words: In a conversation, a speaker of Sámi would expect a larger variety of options to express snow, as opposed to an English user.
  • Specialization of words: Some available expressions in a given language may be too specific to be useful as part of a conversational experience. For example, consider the Sámi word guoldu, which means "a cloud of snow which blows up from the ground when there is a hard frost without very much wind". While this term is technically a way to indicate a type of snow, it may not be of any practical use to a Sámi-speaking user of your Action.

Prompts

Prompts are used to guide users through conversations with your Action. These inform the user of what your Action can do, as well as ask for specific information you need to fulfill their requests.

When localizing prompts, it's important to consider different languages and cultures can have different expectations about what constitutes a "good conversation".

For example, the Japanese language has an extensive grammatical system to express politeness and formality, that translates to three main politeness levels: kudaketa (the plain form), teinei (the simple polite form), and keigo (the advanced polite form).

Choosing which form to use depends on a variety of factors that determine which level of formality each individual should use when addressing another individual. For the Japanese localization of your Action this means two things:

  • Understanding which level to use when addressing your users.
  • Providing localized prompts for the required level(s) of formality.