Ir para o conteúdo principal

Visão Geral

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

npm Version

Bem-vindo à documentação do React Intl! Este é o lugar para encontrar a documentação do React Intl. Sinta-se à vontade para abrir um pull request e contribuir com a documentação para melhorá-la.

Requisitos de Runtime​

Suportamos IE11 e as 2 versões mais recentes do Edge, Chrome, Firefox e Safari.

O React Intl depende destas APIs Intl:

Se você precisa dar suporte a navegadores mais antigos, recomendamos o seguinte:

  1. Se estiver dando suporte a navegadores sem Intl, inclua este polyfill na sua build.

  2. Implemente polyfill para Intl.NumberFormat com @formatjs/intl-numberformat.

  3. Implemente polyfill para Intl.DateTimeFormat com @formatjs/intl-datetimeformat

  4. Se estiver dando suporte a navegadores sem Intl.PluralRules (ex: IE11 e Safari 12-), inclua este polyfill na sua build.

  5. Se estiver dando suporte a navegadores sem Intl.RelativeTimeFormat (ex: IE11, Edge e Safari 12-), inclua este polyfill na sua build junto com dados CLDR individuais para cada localidade suportada.

  6. Se precisar de Intl.DisplayNames, inclua este polyfill na sua build junto com dados CLDR individuais para cada localidade suportada.

Node.js​

full-icu​

A partir do Node.js 13.0.0, o full-icu é suportado por padrão.

Se estiver usando React Intl em versões anteriores do Node.js, seu binário node deve:

OU

Se sua versão do node não tiver alguma das APIs Intl acima, você precisará implementá-las via polyfill adequadamente.

React Native​

Se estiver usando react-intl no React Native, certifique-se que seu runtime tenha suporte nativo a Intl (similar à variante internacional do JSC). Consulte estas issues para mais detalhes:

React Native no iOS​

Se não puder usar a variante Intl do JSC (ex: no iOS), siga as instruções em Requisitos de Runtime para implementar polyfill dessas APIs adequadamente.

O Pacote react-intl​

Instale o pacote npm react-intl via npm:

npm i -S react-intl

O pacote npm react-intl distribui os seguintes módulos (links do unpkg):

  • CommonJS: dependências não empacotadas, "main" no package.json, avisos em desenvolvimento.

  • ES6: dependências não empacotadas, "module" no package.json, avisos em desenvolvimento.

Empacotadores de Módulos​

Otimizamos o React Intl para funcionar bem com empacotadores como: Browserify, Webpack ou Rollup, que podem ser usados para empacotar o React Intl para navegadores:

  • O campo "browser" no package.json é especificado para incluir apenas dados de localidade básicos em inglês durante o empacotamento. Assim, ao usar o módulo "main" no Node, todos os dados de localidade são carregados, mas ignorados quando empacotados para navegador.

  • Uma versão ES6 do React Intl é fornecida como "jsnext:main" e "module" no package.json e pode ser usada com Rollup.

  • Os avisos de desenvolvimento são envolvidos com process.env.NODE_ENV !== 'production', permitindo especificar NODE_ENV durante o empacotamento e minificação para remover esses blocos de código.

O Módulo React Intl​

Seja usando a versão ES6, CommonJS ou UMD do React Intl, todas fornecem as mesmas exportações nomeadas:

react

Ao usar a versão UMD do React Intl sem um sistema de módulos, ela esperará que react exista na variável global: React, e colocará as exportações nomeadas acima na variável global: ReactIntl.

Criando um Contexto de I18n​

Agora com o React Intl e seus dados de localidade carregados, um contexto de i18n pode ser criado para seu aplicativo React.

O React Intl utiliza o padrão provider para delimitar um contexto i18n a uma árvore de componentes. Isso permite que configurações como locale atual e mensagens traduzidas sejam fornecidas na raiz da árvore e disponibilizadas aos componentes <Formatted*>. É o mesmo conceito usado por frameworks Flux como Redux para prover acesso a stores.

Todos os aplicativos que usam React Intl devem usar o componente <IntlProvider>.

O uso mais comum é envolver seu componente raiz do React com <IntlProvider> e configurá-lo com a localidade atual do usuário e as strings/mensagens traduzidas correspondentes:

ReactDOM.render(
  <IntlProvider locale={usersLocale} messages={translationsForUsersLocale}>
    <App />
  </IntlProvider>,
  document.getElementById('container')
)

Consulte: A documentação <IntlProvider> para mais detalhes.

Formatando Dados​

O React Intl tem duas maneiras de formatar dados: através de componentes React e sua API. Os componentes fornecem uma maneira idiomática do React de integrar a internacionalização em um aplicativo React, e os componentes <Formatted*> têm benefícios sobre o uso direto da API imperativa. A API deve ser usada quando seu componente React precisa formatar dados para um valor de string onde um elemento React não é adequado; por exemplo, um atributo title ou aria, ou para efeito colateral em componentDidMount.

A API imperativa do React Intl é acessada via injectIntl, uma fábrica de Componente de Alta Ordem (HOC). Ela envolverá o componente React passado com outro componente React que fornece a API de formatação imperativa ao componente encapsulado por meio de suas props. (Isso é semelhante ao padrão de conexão com stores encontrado em muitas implementações Flux.)

Aqui está um exemplo usando <IntlProvider>, componentes <Formatted*> e a API imperativa para configurar um contexto de i18n e formatar dados:

import React from 'react';
import ReactDOM from 'react-dom';
import {IntlProvider, FormattedRelative, useIntl} from 'react-intl';

const MS_IN_DAY = 1e3 * 3600 * 24

const PostDate = ({date}) => {
  const intl = useIntl()
  return (
    <span title={intl.formatDate(date)}>
      <FormattedRelativeTime value={(Date.now() - date)/MS_IN_DAY} unit="day"/>
    </span>
  )
});

const App = ({post}) => (
  <div>
    <h1>{post.title}</h1>
    <p>
      <PostDate date={post.date} />
    </p>
    <div>{post.body}</div>
  </div>
);

ReactDOM.render(
  <IntlProvider locale={navigator.language}>
    <App
      post={{
        title: 'Hello, World!',
        date: new Date(1459913574887),
        body: 'Amazing content.',
      }}
    />
  </IntlProvider>,
  document.getElementById('container')
);

Supondo que navigator.language seja "en-us":

<div>
  <h1>Hello, World!</h1>
  <p><span title="4/5/2016">yesterday</span></p>
  <div>Amazing content.</div>
</div>

Consulte: A documentação API e Componentes para mais detalhes.

Build ESM

O react-intl e suas bibliotecas subjacentes (@formatjs/icu-messageformat-parser, intl-messageformat, @formatjs/intl-relativetimeformat) exportam artefatos ESM. Isso significa que você deve configurar sua cadeia de ferramentas de build para transpilar essas bibliotecas.

Jest​

Adicione transformIgnorePatterns para sempre incluir essas bibliotecas, por exemplo:

{
  transformIgnorePatterns: [
    '/node_modules/(?!intl-messageformat|@formatjs/icu-messageformat-parser).+\\.js$',
  ],
}

webpack​

Se você está usando babel-loader ou ts-loader, pode fazer uma das seguintes opções:

  1. Adicionar essas bibliotecas em include:
{
  include: [
    path.join(__dirname, 'node_modules/react-intl'),
    path.join(__dirname, 'node_modules/intl-messageformat'),
    path.join(__dirname, 'node_modules/@formatjs/icu-messageformat-parser'),
  ]
}

OU

  1. Adicionar essas bibliotecas em exclude:
exclude: /node_modules\/(?!react-intl|intl-messageformat|@formatjs\/icu-messageformat-parser)/,

Conceitos Fundamentais

  • Formatadores (Data, Número, Mensagem, Relativo)

  • Provedor e Injetor

  • API e Componentes

  • Descritor de Mensagem

  • Sintaxe de Mensagem

  • Definindo mensagens padrão para extração

  • Formatos personalizados e nomeados

Aplicativos de Exemplo

Há vários aplicativos executáveis de exemplo neste repositório Git. Eles são uma ótima maneira de ver os conceitos fundamentais do React Intl em ação em aplicações simplificadas.

Referência da API

O React Intl fornece e é construído sobre algumas camadas de API. Ao usar o React Intl, você interagirá com os built-ins Intl, a API do React Intl e seus componentes React:

Uso com TypeScript

O react-intl é escrito em TypeScript, portanto, possui suporte de primeira classe a TS.

Para usar o react-intl em TypeScript, certifique-se de que a configuração lib das compilerOptions inclua ["esnext.intl", "es2017.intl", "es2018.intl"].

Tipagem de IDs de mensagem e localidade​

Por padrão, o tipo da prop id do <FormattedMessage> e do formatMessage é string. No entanto, você pode definir um tipo mais restritivo para obter autocompletar e verificação de erros. Para fazer isso, substitua o seguinte namespace global pelo tipo de união de todos os seus IDs de mensagem. Você pode fazer isso incluindo o seguinte em algum lugar do seu código:

declare global {
  namespace FormatjsIntl {
    interface Message {
      ids: keyof typeof messages
    }
  }
}

Onde messages é o objeto que você normalmente passaria para <IntlProvider>, e teria a seguinte aparência:

const messages = {
  greeting: 'Hello',
  planet: 'World',
  // ...
}

Você também pode substituir o seguinte global para usar um tipo personalizado para localidade

declare global {
  namespace FormatjsIntl {
    interface IntlConfig {
      locale: 'en' | 'fr'
    }
  }
}

Tipagem de formatos personalizados​

Por padrão, o tipo da prop format de <FormattedDate>, <FormattedDateParts>, <FormattedTime> e <FormattedTimeParts> é string. O mesmo se aplica à configuração format de formatDate, formatDateParts, formatTime e formatTimeParts. Porém, você pode definir um tipo mais restritivo para obter autocompletar e verificação de erros. Para isso, substitua o seguinte namespace global pelo tipo união de todos os nomes dos seus formatos personalizados. Você pode fazer isso incluindo o seguinte em algum lugar do seu código:

declare global {
  namespace FormatjsIntl {
    interface Formats {
      date: keyof (typeof customFormats)['date']
      time: keyof (typeof customFormats)['time']
    }
  }
}

Onde customFormats é o objeto que você normalmente passaria para <IntlProvider>, e teria uma aparência semelhante a:

const customFormats = {
  date: {
    short: {
      month: 'numeric',
      day: 'numeric',
      year: '2-digit',
    },
  },
  time: {
    short: {
      hour: 'numeric',
      minute: 'numeric',
    },
  },
}

Uso Avançado

Nosso Guia de Uso Avançado tem orientações adicionais para configuração de produção em ambientes onde o desempenho é importante.

Ferramentas Suportadas

Extração de mensagens​

Construímos o @formatjs/cli que ajuda a extrair mensagens de uma lista de arquivos. Ele usa o babel-plugin-formatjs internamente e deve ser capaz de extrair mensagens se você estiver declarando usando um dos mecanismos abaixo:

import {defineMessages} from 'react-intl'

defineMessages({
  foo: {
    id: 'foo',
    defaultMessage: 'foo',
    description: 'bar',
  },
})
import {FormattedMessage} from 'react-intl'
;<FormattedMessage id="foo" defaultMessage="foo" description="bar" />
function Comp(props) {
  const {intl} = props
  return intl.formatMessage({
    // The whole `intl.formatMessage` is required so we can extract
    id: 'foo',
    defaultMessage: 'foo',
    description: 'bar',
  })
}

Plugin ESLint​

Também construímos o eslint-plugin-formatjs que ajuda a impor regras específicas em suas mensagens se seu fornecedor de tradução tiver restrições.