The Messages app is a GraphQL service that manages translations for React and GraphQL apps.

Messages aggregates all the translation services in VTEX IO. Given a message to translate, Messages will get the translation in the order presented below.

1. User-defined content.
2. Translations defined in the app's /messages folder.
3. Automatic translation system.

If a translation is not found in one step, Messages proceeds to the next in the list.

The Messages app has some optional configurations. By default, it will translate every string to every available language.

To configure the app settings, follow these steps:

1. In the VTEX Admin, go to Apps > Extensions Hub > App Management.
2. In the list of installed apps, search for VTEX Messages.
3. Click Settings ⚙️.
4. Edit the settings as wanted.
5. Click Save.

See the details about all the settings in the table below:

Setting	Type	Description
Enable User Translations	boolean	Enable user translations of apps' messages. Default: true.
Default Language	string	The default language you want to fallback to. If the value is *, all languages will be supported. Default: *.
Supported Languages	array of strings	List of supported languages. If the requested language is unsupported, the Messages app will translate to the default language.
Two Factor URL	string	URL to receive a token for authorizing message saves.
Enable Automatic Translations	boolean	Enable the items not translated manually on your site to be automatically translated. Default: true.

To translate a frontend app, ensure you are using the Messages builder at version 1.x and the React builder at version 3.x.

Create a folder named /messages in your app's root directory. This folder will contain all translations for your app. For example, to support the Italian language, add a file called it.json with the following content:

This is a key-value JSON where the key is the id used in <FormattedMessage> of React Intl, and the value is the desired translation. Since translating all strings manually is an arduous process, we recommend using automatic translation for languages not part of your target audience.

To leverage better automatic translations, create a file called context.json in your /messages folder with the following content:

This file works as a translation disambiguation. For example, the Italian word "Ciao" could mean both "Hello" and "Goodbye", so the description ensures the translation is accurate.

The context.json file is necessary and has to contain all translation keys.

Best practice: Use keys with spaces for better organization. If there is no translation to the target language for that key, the Messages app will attempt to fall back to the English translation (defined by the user or in the en.json file). If that fails, the key will be translated to the target language using the automatic translation system.

Translating our backend app's response can be done in two steps:

1. Write scalar IOMessage in the first line of the app’s schema.graphql file.
2. Change from String to IOMessage the data that you want to be translatable.

IOMessage is a built-in GraphQL object type used for translatable strings. For more information, see the IOMessage section.

Suppose that you have a GraphQL app that has the following schema:

To return a product with a translatable name and categories, your app's schema should be like the one below:

Now, these fields will automatically be translated into any supported language, without requiring changes to how data is returned or stored.

It's also possible to export custom translations to Messages via a custom app. This can be handy if you want to translate external API data, like the Catalog.

To export such configurations:

1. Create an app with Messages builder at version 1.x.
2. Create a /messages folder in the app's root directory with the desired translations.

For example, if the product name "Cool Shorts" is automatically translated into Portuguese as "Bermuda legal", but you want to override it, create the following files in your app's /messages folder:

Now, "Cool Shorts" will be translated to "Super Bermuda" in Portuguese, overriding the automatic translation.

This section provides an overview of how to work with the Messages API. For more details, see the Messages GraphQL API reference.

The IOMessage is an object type built into our GraphQL infrastructure used for translatable strings. It has the following structure:

• content: String that will be translated.

• description: Description of the context of the string.

• from: Source language of content.

Note that, if your GraphQL resolver returns the IOMessage object structure instead of a raw string, Messages would have more information allowing it to generate an even better translation. On the other hand, if your backend does not provide such info, you can return a raw string and the other parameters will be populated automatically.

• The automatic translations service supports ICU MessageFormat, however each component of the message is translated independently. Therefore, the automatic translation is not optimal and it is better to have a defined translation for complex ICU messages.

• If a message has brackets ({), Messages will assume it is an ICU Message. Therefore, if a bracket is part of your string, you should escape it (\{).

• When trying to translate a React app message to a language that does not have a JSON file in the /messages folder, the Messages app sends the value defined in the en.json file to the automatic translation service. Therefore, it is a good practice to have this file in all React apps.

• When translating a message to a full locale (e.g. pt-BR) and the respective file (pt-BR.json) is not found, Messages will try using the JSON file with only the language (in this example, pt.json).