Práticas de internacionalização no VTEX IO

Práticas de internacionalização no VTEX IO

Introdução

Com o bloco customizado na loja, devemos aprender a internacionalizar o conteúdo apresentado.

É importante lembrar que os blocos devem sempre seguir boas práticas de localização, e não devem mostrar strings hardcoded, mas sim sensíveis a linguagem que a loja opera.

Não se preocupe, você não precisará adicionar traduções de todos os textos para as variadas linguagens nas quais o Store Framework é usado. Portanto, nessa etapa, serão apresentados conceitos acerca da internacionalização de apps e como fazê-la.

As Messages

O conceito de messages facilita a adição de novos idiomas ao tema. As messages centralizam todos os serviços de tradução na plataforma. Dado um texto a ser traduzido, Messages irá primeiramente checar o contexto definido pelo usuário para, em seguida, checar as traduções das apps e, por fim, passa pelo sistema de tradução automática.

Na estrutura do diretório, é possível observar que há uma pasta chamada messages, que apresenta três arquivos principais: pt.json, en.json e es.json, cada um responsável pelas traduções: português, inglês e espanhol, respectivamente. Além disso, a fim de fornecer traduções automáticas melhores, é utilizado o arquivo context.json, responsável por evitar ambiguidades.

Para utilizar tais definições, os arquivos de tradução mencionados anteriormente são JSON, cujas chaves são as mensagens e os valores são as traduções.

O arquivo context.json é necessário e precisa conter todas as mensagens, além de oferecer as traduções automáticas em casos excepcionais.

Internacionalizando seu bloco

Você já deve ter aprendido a usar o nosso builder messages, e será através dele que serão adicionadas strings internacionalizadas nos componentes.

  1. Para isso, na pasta /messages, adicione agora uma mensagem de título para o componente:

    messages/pt.json

    {
      ...,
    +  "countdown.title": "Contagem Regressiva"
    }
    

    messages/en.json

    {
      ...,
    +  "countdown.title": "Countdown"
    }
    

    messages/es.json

    {
      ...,
    +  "countdown.title": "Cuenta Regresiva"
    }
    

    messages/context.json

    {
      ...,
    +  "countdown.title": "Countdown"
    }
    
  2. Feito isso, para renderizar o título deve-se usar o componente FormattedMessage da biblioteca react-intl.

    A biblioteca react-intl dá suporte a várias maneiras de configuração e internacionalização, vale a pena verificá-las.

  3. Agora, adicione a biblioteca usando yarn add react-intl na pasta react. Feito isso, no código do seu componente Countdown.tsx,importe o FormattedMessage

    //react/Countdown.tsx
    +  import { FormattedMessage } from 'react-intl'
    
  4. Também é necessário adicionar uma nova prop ao CountdownProps:

    interface CountdownProps {
    + title: string
      targetDate: string
    }
    
  5. Além disso, adicione uma constante que será o seu título:

    //react/Countdown.tsx
    const titleText = title || <FormattedMessage id="countdown.title" />
    
  6. Agora, junte o título e o contador para renderizá-los. Para isso, defina um container por fora. Além disso, o texto do título será passado através da prop title:

    //react/Countdown.tsx
    const Countdown: StorefrontFunctionComponent<CountdownProps> = ({
      title,
      targetDate,
    }) => {
      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`}>
            {`${timeRemaining.hours}:${timeRemaining.minutes}:${timeRemaining.seconds}`}
          </div>
        </div>
      )
    }
    
  7. Note que são utilizados três handles novos: container, countdown e title. Dessa forma, lembre-se de declará-los na constante CSS_HANDLES, vista na etapa anterior:

    //react/Countdown.tsx
    const CSS_HANDLES = ['container', 'countdown', 'title']
    
  8. Por fim, é preciso adicionar a prop de title no schema:

    //react/Countdown.tsx
    Countdown.schema = {
      title: 'editor.countdown.title',
      description: 'editor.countdown.description',
      type: 'object',
      properties: {
    +   title: {
    +     title: 'Sou um título',
    +     type: 'string',
    +     default: null,
    +   },
        targetDate: {
          title: 'Data final',
          description: 'Data final usada no contador',
          type: 'string',
          default: null,
        },
      },
    }
    

Pronto! Agora, para testar sua loja em outros idiomas basta adicionar a query string /?cultureInfo=pt-br ou /?cultureInfo=es-ar na URL, por exemplo. Ao utilizar tal URL, o resultado esperado é esse aqui:

imageimage

Está com dúvidas?

Veja o gabarito para esta etapa ou participe do nosso office hours


Ajude-nos a fazer este conteúdo melhor!

Os cursos do VTEX IO são de código aberto. Se você perceber algum problema, pode abrir um pull request!

Faça uma contribuição

ou abra uma issue