Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center


Localizing Capsules

If you want to make your capsule accessible worldwide, you need to make your capsule available in multiple languages. This topic describes how to create translatable files for your capsule.

Externalizing Strings

Most translation processes involve sending separate files of pre-formatted strings to a localization group. That group translates these files of strings into various languages (manually or through software), without knowing the code that these strings accompany. We recommend following a similar process of externalizing your text (in dialogs and layouts) for maximum efficiency when localizing your capsules. You would do this through template macros.

Specifically, we recommend that you have a separate template-macro-def file for all layouts and, when reasonable, for dialogs. Then, for each language, you can place a translated copy in the appropriate resources language folder.

Your workspace might look similar to this:

    - base
        - MyCapsule.Results.layout.bxb
    - en
        - MyCapsule.MyConcept.dialog.bxb
        - MyCapsule.UI-string.dialog.bxb
    - ko
        - MyCapsule.MyConcept.dialog.bxb
        - MyCapsule.UI-string.dialog.bxb

Externalizing strings enables you to easily identify what text needs to be translated without requiring your translation team to understand the complexity of underlying code.

Writing Dialog for Translation

This section briefly discusses the tools you can use when writing dialogs. For more information on dialogs in general, see Refining Dialog in the developer's guide and Dialog Reference in the reference documentation.

Dialog Fragments

Dialog fragments are a powerful tool that enable you to reuse dialog text multiple times in multiple places.

For example, you can use the following basic concept Dialog for restaurants:

dialog (Concept) {
match: viv.restaurant.Restaurant (this)
switch (plural(this)) {
case (One) {
template (restaurant)
} default {
template (restaurants)

You can learn more about how to implement dialog fragments in the reference topic. Note that using dialog fragments involve trade-offs.

Dialog Template Macros

Dialog template macros are another useful tool that enable you to reuse dialog in multiple places. You define the text that is replaceable with the template-macro-def key and then use template-macro to invoke the definition.

Note that you can choose to have as many template-macro-def definitions in a single file as you want. Here is an example for a recipe capsule in which you declare three dialog macros:

template-macro-def(Bookmarks) {
params {
param (number) {
type (viv.recipe.TotalTries)
max (One) min (Required)
content: template ("#{value(number)} bookmarks")
template-macro-def (CaloriesPerServing) {
params {
param (calories) {
type (viv.nutrition.Calories)
max (One) min (Required)
content: template ("#{integer(calories)} Cal/serving")
template-macro-def (CookingTime) {
params {
param (number) {
type (viv.recipe.TotalTime)
max (One) min (Required)
content: template ("Ready in #{value(number)}")

You can learn more about implementing template macros in the developer's guide.

Writing Layouts for Translation

We recommend creating a UI-strings.dialog.bxb file for your capsule that handles any UI text for your layouts. For example, if you have a flight capsule, you should create a flight.UI-strings.dialog.bxb file that contains template-macro-def declarations for all text in the UI. You can then use template-macro keys in your layouts and layout macros.

For example:

<layout mode="Details">
viv.testNamedDialog.TestConcept (this)
<template-macro id="id2"><x>{{this}}</x><t>some text</t></template-macro>

For more information on developing layouts, see Layouts in the developer's guide.

Layout Macros

Layout macros are a way for you to use shared layouts in your capsules. While this is not something you need to localize your capsule, it can be useful when combined with template-macros. Similar to template-macro-def, you would use a layout-macro-def to define a general layout with different parameters as needed. Then, you would use layout-macro to invoke the layout macro by using the id you defined in the layout-macro-def.

For more information on how to implement layout macros, see Layout Macros in the developer's guide.

Trade Offs of Fragmentation

It is important to note that there is a trade-off between creating compositional dialog versus keeping entire sentences together for translation.

As explained in dialog fragments, there are several benefits to creating these building blocks of text. If you have the same concept that appears in 20 different places in your capsule's dialog, you would have one concept fragment dialog file that handles this text. If you have your capsule available in 4 different languages, this now becomes 80 different places you might have to keep track of and change!

However, depending on the language, these building blocks might not compose comprehensible sentences once translated. The resulting utterances from Bixby would then end up sounding unnatural or worse, incorrect!

For example, English has no concept of gender with respect to inanimate objects like other Romance languages. When developing a capsule to find furniture for someone based on their favorite color, you might use the following dialog:

dialog (Concept){
match: FindTables (output) {
from-input: FavoriteColor (action)
template ("Here are some #{value(action.color)} tables!")

Your result prints Here are some red tables in English but the translated Spanish text might read Aquí hay algunas mesas rojos instead of the correct Aquí hay algunas mesas rojas. While this is clearly an over-simplified example, it can easily be extended to more complex situations, especially considering the different grammar between languages.

Therefore, when developing, keep in mind that there might be certain situations where your dialog would benefit from keeping output whole or from just depending on the platform to craft its own response.

Localizing Storage Prompts

To localize storage prompts, which are generated when Bixby asks for permission to store a preference in the user's profile, you can create localized *.profile.bxb files. These files contain profile-support blocks that specify match patterns and new dialog for prompts. These files go in the appropriate resources language folder, just like template-macro-def files:

    - en
        - MyStoragePrompt.profile.bxb
    - ko
        - MyStoragePrompt.profile.bxb

An example profile.bxb file looks like this:

profile-support {
match: FlightPreferences
storage-prompt {
confirmation-type (PreferenceConfirmation)
message (Store your flight preferences?)
confirm-label (Yes)
deny-label (No)

For more details, see the profile-support documentation.

Prepare Your capsule.bxb File

In order to make sure that Bixby properly interprets the contents of your capsule, you will need to make sure that your capsule.bxb file lists all the target devices and locales that you want supported, as explained in the Provide Targets section of preparing your capsule. If you have a target specified, but do not want it enabled, set that target's enabled key to false.

The list of supported devices and locales are in the target reference.

You can also further customize the countries and device models that your capsule supports by providing marketplace constraints.

Localized Training

You need to train your capsule in each localized language, so that Bixby can learn how to interact with its users.

  1. Make sure you've added the targets to your capsule.bxb file. This step ensures that the right devices and languages can be set when creating a new training file.
  2. Create a new training file under the appropriate resources language folder.
  3. In the Create New File pop-up, select the appropriate device and language and click Create.
  4. Start localized training!

It's important to note that training and annotating the utterances work essentially the same across all languages! While you might have subtle differences in tokenizing words, the general guidelines are the same for all locales. If there is an issue with your training entry, Bixby Developer Studio will inform you of the invalidity. You should make sure to thoroughly train your capsule per language to improve Bixby's interaction with all users.