Internationalization practices in VTEX IO

Internationalization practices in VTEX IO


With the customized block in the store, we need to learn to internationalize the content presented.

It is important to remember that blocks must always follow good localization practices, and must not show hardcoded strings, but ones that are sensitive to the language that the store operates.

Don't worry, you won't need to add translations of all texts for the various languages in which the Store Framework is used. Therefore, in this stage, will be presented concepts about the internationalization of apps and how to do it.

The Messages

The concept of messages makes it easy to add new languages ​​to the theme. The Messages centralize all translation services on the platform. Given a text to be translated, Messages will first check the user-defined context, then check the translations of the apps and, finally, go through the automatic translation system.

In the directory structure, you can see that there is a folder called messages, which has three main files: pt.json, en.json, andes.json, each responsible for the translations: Portuguese, English, and Spanish, respectively. In addition, in order to provide better automatic translations, the context.json file is used, which is responsible for avoiding ambiguities.

To use such definitions, the translation files mentioned above are JSON, whose keys are messages and values ​​are translations.

The context.json file is necessary and must contain all messages, besides offering automatic translations in exceptional cases.

Internationalizing your block

You must have learned how to use our builder messages, and it will be through it that internationalized strings will be added to the components.

  1. To do so, in the directory /messages, add now a message for the title of the component:


    +	"countdown.title": "Contagem Regressiva"


    +	"countdown.title": "Countdown"


    +	"countdown.title": "Cuenta Regresiva"


    +	"countdown.title": "Countdown"
  2. After that, to render the title the component FormattedMessage of the lib react-intl must be used.

    The lib react-intl supports many ways of configuration and internationalization, it is worth checking it out.

  3. Now, add the lib using yarn add react-intl in the react directory. After doing that, in your component's code, Countdown.tsx, import the FormattedMessage:

    import { FormattedMessage } from 'react-intl'
  4. And add a new prop to the interface CountdownProps:

    interface CountdownProps {
    + title: string
      targetDate: string
  5. You'll also need to add a const that will be your title:

    const titleText = title || <FormattedMessage id="countdown.title" />
  6. Now, join the title to the countdown to render. To do so, define a container outside. Besides, the text for the title will be passes using the prop title:

    const Countdown: StorefrontFunctionComponent<CountdownProps> = ({
    }) => {
      const [timeRemaining, setTime] = useState<TimeSplit>({
        hours: '00',
        minutes: '00',
        seconds: '00',
      const titleText = title || <FormattedMessage id="countdown.title" />
      const handles = useCssHandles(CSS_HANDLES)
      tick(targetDate, setTime)
      return (
        <div className={`${handles.container} t-heading-2 fw3 w-100 c-muted-1`}>
          <div className={`${handles.title} db tc`}>{titleText}</div>
          <div className={`${handles.countdown} db tc`}>
  7. Note that three new handles are used: container, countdown and title. Therefore, remember to declare them in the const CSS_HANDLES, seen in the previous step:

    const CSS_HANDLES = ['container', 'countdown', 'title']
  8. At last but not least, it is needed to add the title prop in the schema:

    Countdown.schema = {
      title: 'editor.countdown.title',
      description: 'editor.countdown.description',
      type: 'object',
      properties: {
    +   title: {
    +     title: 'I am a title',
    +     type: 'string',
    +     default: null,
    +   },
        targetDate: {
          title: 'Final date',
          description: 'Final date used in the countdown',
          type: 'string',
          default: null,

Done! Now, to try out your store in other languages, you just need to add the query string /?cultureInfo=pt-br or /?cultureInfo=es-ar on the URL, for example. By using the first URL, the expected result is this one:


Any questions?

See the answersheet for this step or check our [office hours] on the VTEX Developers channel(

Help us make this content better!

VTEX IO courses are open source. If you see something wrong, you can open a pull request!

Make a contribution

or open an issue