Join the Actions on Google Developer Challenge to win a trip to Google I/O 2018 and more than 20 other prizes.

Localization Best Practices

By default, your app is available in all regions as long as the user's Assistant language is set to an "English" variant (for example, en-US or en-GB). You can cater your apps for different locales in the console or in your fulfillment, in the following ways:

  • Location targeting: You can specify regions that your app is available in the Actions Console. By default, your app supports all regions.
  • TTS voice customization: By default, your app automatically uses a set of TTS voices that is best suited for the user's Assistant locale. You can override this behavior and choose a specific TTS voice for your app that doesn't change based on the user's Assistant locale.
  • Locale-specific responses: You receive the user's Assistant locale setting in each request to your fulfillment and can use it to return different responses based on the locale.

Targeting locations

The Actions console lets you control region availability with the Location targeting setting, which specifies the regions your app supports. A device's region is determined by its physical location and not by its locale. Regions are currently set at the country level.

You might want to use location targeting if you have an app that only allows purchases in certain countries or if your app relies on the user physically being in a specific country to use it. However, you should make your app available to as many regions as possible. For instance, if you create an app that teaches users about United States history, you should make the app available to all regions to get the most usage and exposure.

To set location targeting:

  1. Go to the Overview section of your project in the Actions console.
  2. In the Location targeting section, specify the regions that your app supports. By default, all regions are supported.

Customizing TTS voice

By default, your app uses the TTS voice associated with the user's Assistant locale setting. This setting is usually the same as the device's locale setting, but can be different if the user explicitly changes the Assistant's locale.

If desired, you can force a specific TTS voice for your app, regardless of the Assistant locale setting. For example, you might want to do this if you have a persona that must have an American or British English accent.

To set a specific TTS voice for your app:

  1. Go to the Actions Console and click on your project. The Overview page appears.
  2. Click on App Information > Details to display the Assistant app voice field. The default setting of Match user's language setting is selected by default.
  3. To override the default setting, deselect the Match user's language setting checkbox and choose the desired TTS voice from the drop-down menu.

Providing locale-specific responses

You receive the Assistant locale (a combination of the user's language and region setting) in every request to your fulfillment. With this information, you can can do locale-based logic, such as specifying slightly different responses or spellings for US English versus British English:

// Use ActionsSdkApp instead of ApiAiApp for the Actions SDK
const app = new ApiAiApp({request, response});

...

const prompts = {
  'en-US': `Alright, what's your favorite color?`,
  'en-GB': `Alright, what's your favourite colour?`
};

app.ask(prompts[app.getUserLocale()]);

...

Another example might be notifying the user that a portion of your app is not supported, unless the user has a specific locale set.

// Use ActionsSdkApp instead of ApiAiApp for the Actions SDK
const app = new ApiAiApp({request, response});

...

if (app.getUserLocale() === 'en-US') {
  // do some logic and return a response normally
}
else {
  app.ask("Sorry, this portion of the app is not supported outside of the
    United States. Tell me what else you want to do.");
}

...

Providing more varied user expressions

If you're using API.AI, provide more User says phrases for variants of a language (for example, different phrases for US English and British English). This allows your language understanding model to be more robust and handle different expressions for language dialects.

Testing

To test out your app in different locales, change the Assistant locale setting on a hardware device (see instructions for Google Home or Android devices).

The Actions Simulator also lets you simulate the locale and physical location of the user running the app:

  1. Go to the Actions Console and click on your project.
  2. Click on the Actions Simulator menu item in the left navigation.
  3. Click the Language drop-down menu to select a language for the simulator. Ensure any locale-specific logic that you've done is carried out correctly.
  4. Click the Location field to enter a location or drop a pin on the location you'd like to simulate. Ensure any location-specific logic that you've done is carried out correctly.