Messages GraphQL API by vtex

This article serves as a comprehensive reference for the GraphQL API provided by the Messages app. This API enables the internationalization of messages in various store contexts, such as Catalog, Intelligent Search, and VTEX IO apps. For more details about how this API is used, see the Overwriting the Messages app article.

Schema overview

Query

classDiagram
  direction LR
  class Languages {
    supported [String!]!
    default String!
  }

  class Translation {
    lang String!
    translation String!
  }

  class MessageListV2 {
    srcLang String!
    groupContext String
    context String
    translations [Translation!]!
  }

  class Query {
    languages Languages!
    translate(args TranslateArgs!) [String]!
    translateWithDependencies(args TranslateWithDependenciesArgs!) [String]!
    userTranslations(args IndexedMessages!) [MessageListV2]!
    listV2(args ListArgsV2!) [MessageListV2!]!
    authorize Boolean!
  }

  Query --> Languages : languages
  MessageListV2 --> Translation : translations
  Query --> MessageListV2 : userTranslations
  Query --> MessageListV2 : listV2

  click Query href "#query"
  click Languages href "#languages"
  click MessageListV2 href "#messagelistv2"
  click Translation href "#translation"

Field	Type	Description
languages	Languages!	Returns the store's default locale and the list of supported languages. These values are defined in the Default Language and Supported Languages settings in the Messages app settings.
translate	[String]!	Endpoint that retrieves a list of translated messages from a specific locale in Catalog.
args	TranslateArgs!	Input for translation requests.
translateWithDependencies	[String]!	Retrieves a list of translated messages from a specific locale in a VTEX IO app. The response is a list of `MessageListV2`, where each element contains a list of messages.
args	TranslateWithDependenciesArgs!	Input for translation requests. Similar to `TranslateArgs` but requires dependency information.
userTranslations	[MessageListV2]!	Retrieves user translations. The response is a list of `MessageListV2`, where each element contains a list of messages from a specific source (CMS, an app, etc.).
args	IndexedMessages!	Group of messages by their source language.
listV2	[MessageListV2!]!	Retrieves a subset of all messages stored in VBase. The `range` argument defines the beginning and the end of the retrieved list. The response is a list of `MessageListV2`, where each element has a list of messages from a specific source (CMS, an app, etc.).
args	ListArgsV2!	Argument used for message pagination.
authorize	Boolean!	Handles authorization for requests outside IO using a two-factor authentication token. It works with the Two Factor URL app setting.

Mutation

classDiagram
  direction LR
  class Mutation {
    saveV2(args SaveArgsV2!) Boolean!
  }

  click Mutation href "#mutation"

Field	(argument)	Type	Description
saveV2		Boolean!	Creates or updates custom messages for the specified locale. This applies to translations for Catalog, Intelligent Search, and installed apps.
args		SaveArgsV2!	Input of messages to be saved.

Schema description

Arguments must be provided by the user. Required fields are marked with an exclamation mark (!).

Languages

Field	Type	Description
supported	[String!]!	A list of languages the store supports. Each language is defined by its locale code in ISO 639-1 format. Example: `en-US`. If the request to the Messages app has a target language that isn't supported, it will translate to the default language, which is defined by Supported Languages in the app settings.
default	String!	The default fallback language for the store, defined by its locale code in ISO 639-1 format. Example: `en-US`. If the value is ``, all languages will be supported. This is defined by Default Language* in the app settings.

Query 🔼

MessageListV2

Field	Type	Description
srcLang	String!	Locale code of the message list source content in ISO 639-1 format. Example: `en-US`.
groupContext	String	Groups related translations based on their context. Apps: `automaticV2`. CMS: `CMS`. Undefined: `null`.
context	String	Defines the context for the translation. For example: Catalog: ID of the product/brand/category you want to translate, found in the Admin under Product > Catalog. Apps: The name of the app in which the message is being overwritten. Intelligent Search: `intelligentSearchFacets`, which defines the context of VTEX Intelligent Search.
translations	[Translation!]!	List of messages in the context.

Query 🔼

IndexedMessages 🔽

Translation

Field	Type	Description
lang	String!	Message locale code in ISO 639-1 format. Example: `en-US`.
translation	String!	The translated message string.

MessageListV2 🔼

IndexedMessages

Field		Type	Description
from		String!	Source message locale code in ISO 639-1 format. Example: `en-US`.
messages		[MessageInputV2!]!	List of messages to check translations. Each item in the list is a message in `MessageInputV2` format.

Query 🔼

TranslateArgs 🔽

TranslateWithDependenciesArgs 🔽

ListArgsV2

Field		Type	Description
range		MessagesRange!	Range indicating the first and last messages in the list.

Query 🔼

MessageInputV2

Field Type Description

content String! Source message string.

Field	Type	Description
content	String!	Source message string.
context	String	Provides context for the message. For example: Catalog: ID of the product/brand/category you want to check the translation, found in the Admin under Product > Catalog. Apps: The name of the app in which the message has been overwritten.
behavior	Behavior	Defines the translation source. The available options are `USER_ONLY`, `USER_AND_APP`, and `FULL`.

context

String

Provides context for the message. For example:

Catalog: ID of the product/brand/category you want to check the translation, found in the Admin under Product > Catalog.
Apps: The name of the app in which the message has been overwritten.

behavior Behavior Defines the translation source. The available options are USER_ONLY, USER_AND_APP, and FULL.

IndexedMessages 🔼

MessageSaveInputV2

Field	Type	Description
srcLang	String!	Store's locale default code in ISO 639-1 format. Example: `en-US`. In the VTEX Intelligent Search context, this variable must be the store's binding default.
srcMessage	String!	The source message based on its context: Catalog: Source message string. Apps: The ID of your message string declared in the app's messages folder. Intelligent Search: Source message string. Check the list below for the possible values of this variable and their definitions. `Category 1`: Department. `Category 2`: Category. `Category 3`: Subcategory. `Price`: Price. `Promotion`: Promotion. `New Release`: New release. `Location`: Location. `Brand`: Brand.
targetMessage	String!	Catalog: Translated message string. Apps: Translated message string. Intelligent Search: Translated message string.
groupContext	String	Groups related translations based on their context. Apps: `automaticV2`. CMS: `CMS`. Undefined: `null`.
context	String	Catalog: ID of the product/brand/category you want to translate, found in the Admin under Product > Catalog. Apps: The name of the app in which the message is being overwritten. Intelligent Search: `intelligentSearchFacets`, which defines the context of VTEX Intelligent Search.

SaveArgsV2 🔽

MessagesRange

Field		Type	Description
from		Int!	Position of the first list element.
to		Int!	Position of the last list element.

ListArgsV2 🔼

SaveArgsV2

Field	Type	Description
to	String!	Target locale code (ISO 639-1 format, for example: `en-US`) for the translation.
messages	[MessageSaveInputV2!]!	List of messages to be translated.
fireEvent	Boolean	If `true`, the request triggers an event. Default: `false`.

Mutation 🔼

TranslateArgs

Field	Type	Description
indexedByFrom	[IndexedMessages!]!	List of `IndexedMessages`. Each item in the list has a locale and a corresponding list of messages.
to	String!	Target locale code (ISO 639-1 format, for example: `en-US`) for the translation.
depTree	String	The dependency tree in the format `"[{"id": "{context}"}]"`. Example: `"[{"id": "vtex.store-components@3.x"}]"`.
encoding	Encoding	The encoding format for messages sent to the automatic translation service. The available formats are `ICU` and `HANDLEBARS`.

Query 🔼

TranslateWithDependenciesArgs

Field	Type	Description
indexedByFrom	[IndexedMessages!]!	List of `IndexedMessages`. Each item in the list has a locale and a corresponding list of messages.
to	String!	Target locale code (ISO 639-1 format, for example: `en-US`) for the translation.
depTree	String!	The dependency tree in the format `"[{"id": "{context}"}]"`. Example: `"[{"id": "vtex.store-components@3.x"}]"`.
encoding	Encoding	The encoding format for messages sent to the automatic translation service. The available formats are `ICU` and `HANDLEBARS`.

Query 🔼

Behavior

Value	Description
USER_ONLY	Only uses translations defined by users, ignoring app and automatic translations.
USER_AND_APP	Uses both user-defined and app-defined translations, but ignores automatic translations.
FULL	Uses all available translation sources.

MessageInputV2 🔼

Encoding

Value	Description
ICU	Use for messages to be encoded in ICU (International Components for Unicode) format through the ICU MessageFormat Parser.
HANDLEBARS	Use for messages to be encoded in Handlebars format.

TranslateArgs 🔼

TranslateWithDependenciesArgs 🔼