The messages builder handles the internationalization (i18n) of strings in VTEX IO apps using React. Instead of declaring static strings in frontend components, this builder allows you to use an ID for each message, which will be dynamically replaced with the corresponding string in the user's language.

For more information about creating apps that support multiple languages, see 7. Translating the component in the Storefront apps and Internationalization.

The messages builder uses a folder named messages located in the app's root folder. This folder contains one JSON file for each language used in the app. Each file is named using the corresponding two lowercase letters of the language's ISO 639-1 code. For instance, English is represented by the code en, Spanish by es, and Portuguese by pt.

• {language-code}.json: JSON file of the language containing the message IDs with their corresponding strings. See file name examples below:

  • en.json: JSON file for English messages.
  • es.json: JSON file for Spanish messages.
  • pt.json: JSON file for Portuguese messages.

To develop an app using the messages builder, follow the steps below:

1. Start with a React app: First, you need an app that uses the react builder. If you are starting from scratch, you can download the React app boilerplate.

2. Add the React i18n libraries: Open a terminal in the react folder of your app and run the following command: yarn add react-intl@3 && yarn add @types/react-intl@3 --dev.

3. Configure the manifest: Access the manifest.json file and add the messages builder to the builders list.

   manifest.json

   
   

   _10

   {

   _10

   ...

   _10

   "builders": {

   _10

   "react": "3.x",

   _10

   "docs": "0.x",

   _10

   + "messages": "1.x"

   _10

   },

   _10

   ...

   _10

   }

   
   

4. Add the message identifiers: Use the string identifiers in your React code. In the example below, store/my-app.hello is a string identifier for the <Formatted Message> component. Keys that start with store/ are used in the storefront, while keys that start with admin/ are used in the Admin UI. If a string identifier is used in the code and does not have a corresponding key in the message JSON files, it will fallback to the automatic translation service.

   
   

   _12

   import React from 'react'

   _12

   import { FormattedMessage } from 'react-intl'

   _12

   _12

   const HelloWorld = () => {

   _12

   return (

   _12

   <div>

   _12

   <FormattedMessage id="store/my-app.hello"/>

   _12

   </div>

   _12

   )

   _12

   }

   _12

   _12

   export default HelloWorld

   
   

   Use meaningful and descriptive keys for all strings. Maintain a consistent naming convention that reflects the context and location of the text. This practice helps developers and translators locate the keys, understand their meaning, and organize the strings.

5. Add the messages files with strings: Create a separate JSON file for each language in the messages folder. In each file, define an object where the keys are the message IDs and the values are the corresponding strings in the target language. Each key must be present in every JSON file. See the examples below for English, Spanish, and Portuguese.

   en.json

   
   

   _10

   {

   _10

   "store/my-app.hello": "Hello, world!"

   _10

   }

   
   
   es.json

   
   

   _10

   {

   _10

   "store/my-app.hello": "¡Hola, mundo!"

   _10

   }

   
   
   pt.json

   
   

   _10

   {

   _10

   "store/my-app.hello": "Olá, mundo!"

   _10

   }

   
   

   We recommend adding the keys to the JSON files in alphabetical order. This helps developers and translators to locate and work with the keys.