Saltar al contenido principal

Introducción

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

npm Version

¡Bienvenido a la documentación de React Intl! Este es el lugar para encontrar la documentación de React Intl. Siéntete libre de abrir un pull request y contribuir a la documentación para mejorarla.

Requisitos de entorno de ejecución​

Admitimos IE11 y las 2 versiones más recientes de Edge, Chrome, Firefox y Safari.

React Intl depende de estas APIs de Intl:

Si necesitas admitir navegadores más antiguos, te recomendamos hacer lo siguiente:

  1. Si estás admitiendo navegadores que no tienen Intl, incluye este polyfill en tu compilación.

  2. Aplica polyfill a Intl.NumberFormat con @formatjs/intl-numberformat.

  3. Aplica polyfill a Intl.DateTimeFormat con @formatjs/intl-datetimeformat

  4. Si estás admitiendo navegadores que no tienen Intl.PluralRules (p. ej., IE11 y Safari 12-), incluye este polyfill en tu compilación.

  5. Si estás admitiendo navegadores que no tienen Intl.RelativeTimeFormat (p. ej., IE11, Edge y Safari 12-), incluye este polyfill en tu compilación junto con los datos CLDR individuales para cada idioma que admitas.

  6. Si necesitas Intl.DisplayNames, incluye este polyfill en tu compilación junto con los datos CLDR individuales para cada idioma que admitas.

Node.js​

full-icu​

A partir de Node.js 13.0.0, full-icu es compatible de forma predeterminada.

Si usas React Intl en una versión anterior de Node.js, tu binario de node debe:

O

Si a tu versión de node le falta alguna de las APIs de Intl mencionadas, deberás aplicarles polyfill correspondientemente.

React Native​

Si usas react-intl en React Native, asegúrate de que tu entorno de ejecución tenga soporte Intl incorporado (similar a la variante internacional de JSC). Consulta estos problemas para más detalles:

React Native en iOS​

Si no puedes usar la variante Intl de JSC (p. ej., en iOS), sigue las instrucciones en Requisitos de entorno de ejecución para aplicar polyfill a esas APIs correspondientemente.

El paquete react-intl​

Instala el paquete npm react-intl mediante npm:

npm i -S react-intl

El paquete npm react-intl distribuye los siguientes módulos (enlaces de unpkg):

  • CommonJS: dependencias no agrupadas, "main" en package.json, advertencias en desarrollo.

  • ES6: dependencias no agrupadas, "module" en package.json, advertencias en desarrollo.

Agrupadores de módulos​

Hemos hecho que React Intl funcione bien con agrupadores de módulos como: Browserify, Webpack o Rollup, que se pueden usar para agrupar React Intl para el navegador:

  • El campo "browser" en package.json se especifica para que solo se incluyan datos locales básicos de inglés al agrupar. De esta manera, al usar el módulo "main" en Node, se cargan todos los datos locales, pero se ignoran cuando se agrupan para el navegador.

  • Se proporciona una versión ES6 de React Intl como "jsnext:main" y "module" en package.json y se puede usar con Rollup.

  • Las advertencias en tiempo de desarrollo están envueltas con process.env.NODE_ENV !== 'production', lo que permite especificar NODE_ENV durante el empaquetado y minificación para eliminar estos bloques de código.

El módulo React Intl​

Ya sea que uses la versión ES6, CommonJS o UMD de React Intl, todas proporcionan las mismas exportaciones nombradas:

react

Al usar la versión UMD de React Intl sin un sistema de módulos, esperará que react exista en la variable global: React, y colocará las exportaciones nombradas anteriores en la variable global: ReactIntl.

Creación de un contexto de i18n​

Ahora con React Intl y sus datos de localización cargados, se puede crear un contexto de i18n para tu aplicación React.

React Intl utiliza el patrón proveedor para delimitar un contexto de i18n a un árbol de componentes. Esto permite configurar propiedades como la localización actual y mensajes traducidos en la raíz del árbol, haciéndolos disponibles para los componentes <Formatted*>. Es el mismo concepto que frameworks Flux como Redux usan para proporcionar acceso a un store.

Todas las aplicaciones que usan React Intl deben utilizar el componente <IntlProvider>.

El uso más común es envolver tu componente raíz de React con <IntlProvider> y configurarlo con la localidad actual del usuario y las cadenas/mensajes traducidos correspondientes:

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

Consulta: La documentación de <IntlProvider> para más detalles.

Formateo de datos​

React Intl tiene dos formas de formatear datos: mediante componentes React y su API. Los componentes proporcionan una forma idiomática de React para integrar la internacionalización en una aplicación, y los componentes <Formatted*> tienen ventajas sobre el uso directo de la API imperativa. La API debe usarse cuando tu componente React necesite formatear datos a un valor de cadena donde un elemento React no sea adecuado; por ejemplo, un atributo title o aria, o para efectos secundarios en componentDidMount.

La API imperativa de React Intl se accede mediante injectIntl, una fábrica de Componentes de Orden Superior (HOC). Envolverá el componente React pasado con otro componente React que proporciona la API de formateo imperativo al componente envuelto a través de sus props. (Esto es similar al patrón de conexión a almacenes que se encuentra en muchas implementaciones de Flux).

Aquí hay un ejemplo usando <IntlProvider>, componentes <Formatted*>, y la API imperativa para configurar un contexto de i18n y formatear datos:

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')
);

Asumiendo que navigator.language es "en-us":

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

Consulta: La documentación de la API y los Componentes para más detalles.

Compilación ESM

react-intl y sus bibliotecas subyacentes (@formatjs/icu-messageformat-parser, intl-messageformat, @formatjs/intl-relativetimeformat) exportan artefactos ESM. Esto significa que debes configurar tu cadena de herramientas de compilación para transpilar esas bibliotecas.

Jest​

Añade transformIgnorePatterns para incluir siempre esas librerías, ej:

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

webpack​

Si usas babel-loader o ts-loader, puedes hacer una de las siguientes:

  1. Añadir esas bibliotecas en 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'),
  ]
}

O

  1. Añadir esas bibliotecas en exclude:
exclude: /node_modules\/(?!react-intl|intl-messageformat|@formatjs\/icu-messageformat-parser)/,

Conceptos básicos

  • Formateadores (Fecha, Número, Mensaje, Relativo)

  • Proveedor e Inyector

  • API y Componentes

  • Descriptor de mensaje

  • Sintaxis de mensajes

  • Definir mensajes predeterminados para extracción

  • Formatos personalizados con nombre

Aplicaciones de ejemplo

Hay varias aplicaciones ejecutables de ejemplo en este repositorio Git. Son una excelente manera de ver los conceptos básicos de React Intl en acción en aplicaciones simplificadas.

Referencia de la API

React Intl proporciona y está construido sobre varias capas de API. Al usar React Intl, interactuarás con las funciones incorporadas de Intl, la API de React Intl y sus componentes de React:

Uso con TypeScript

react-intl está escrito en TypeScript, por lo que tiene soporte de primera clase para TS.

Para usar react-intl en TypeScript, asegúrate de que la configuración lib de compilerOptions incluya ["esnext.intl", "es2017.intl", "es2018.intl"].

Tipado de IDs de mensajes y locales​

Por defecto, el tipo para la propiedad id de <FormattedMessage> y formatMessage es string. Sin embargo, puedes establecer un tipo más restrictivo para obtener autocompletado y verificación de errores. Para hacer esto, anula el siguiente espacio de nombres global con el tipo unión de todos tus IDs de mensaje. Puedes hacerlo incluyendo esto en tu código:

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

Donde messages es el objeto que normalmente pasarías a <IntlProvider>, y se vería algo como:

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

También puedes anular el siguiente global para usar un tipo personalizado para el locale:

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

Tipado de formatos personalizados​

Por defecto, el tipo de la propiedad format en <FormattedDate>, <FormattedDateParts>, <FormattedTime> y <FormattedTimeParts> es string. Lo mismo aplica para la configuración format de formatDate, formatDateParts, formatTime y formatTimeParts. Sin embargo, puedes establecer un tipo más restrictivo para obtener autocompletado y verificación de errores. Para hacer esto, sobreescribe el siguiente espacio de nombres global con el tipo unión de todos tus nombres de formatos personalizados. Puedes hacer esto incluyendo lo siguiente en tu código:

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

Donde customFormats es el objeto que normalmente pasarías a <IntlProvider>, y se vería algo así como:

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

Uso avanzado

Nuestra Guía de uso avanzado incluye más recursos para configuraciones de producción en entornos donde el rendimiento es crítico.

Herramientas compatibles

Extracción de mensajes​

Hemos construido @formatjs/cli que te ayuda a extraer mensajes de una lista de archivos. Usa babel-plugin-formatjs internamente y debería poder extraer mensajes si los declaras usando uno de estos mecanismos:

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​

También hemos construido eslint-plugin-formatjs que ayuda a aplicar reglas específicas en tus mensajes si tu proveedor de traducciones tiene restricciones.