Zum Hauptinhalt springen

Übersicht

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

npm Version

Willkommen in der Dokumentation von React Intl! Hier finden Sie alle Dokumentationen zu React Intl. Sie können gerne einen Pull Request öffnen und zur Verbesserung der Dokumentation beitragen.

Laufzeitanforderungen​

Wir unterstützen IE11 und die beiden neuesten Versionen von Edge, Chrome, Firefox & Safari.

React Intl benötigt folgende Intl-APIs:

Falls Sie ältere Browser unterstützen müssen, empfehlen wir folgende Schritte:

  1. Für Browser ohne Intl-Unterstützung: Integrieren Sie dieses Polyfill in Ihren Build.

  2. Polyfillen Sie Intl.NumberFormat mit @formatjs/intl-numberformat.

  3. Polyfillen Sie Intl.DateTimeFormat mit @formatjs/intl-datetimeformat

  4. Für Browser ohne Intl.PluralRules (z.B. IE11 & Safari 12-): Integrieren Sie dieses Polyfill in Ihren Build.

  5. Für Browser ohne Intl.RelativeTimeFormat (z.B. IE11, Edge, Safari 12-): Integrieren Sie dieses Polyfill in Ihren Build zusammen mit individuellen CLDR-Daten für jede unterstützte Locale.

  6. Falls Sie Intl.DisplayNames benötigen: Integrieren Sie dieses Polyfill in Ihren Build zusammen mit individuellen CLDR-Daten für jede unterstützte Locale.

Node.js​

full-icu​

Ab Node.js 13.0.0 ist full-icu standardmäßig unterstützt.

Bei Verwendung von React Intl in älteren Node.js-Versionen muss Ihre node-Binärdatei:

  • Mit full-icu kompiliert werden, gemäß diesen Anleitungen

ODER

Falls Ihre node-Version eine der oben genannten Intl-APIs nicht unterstützt, müssen Sie diese entsprechend polyfillen.

React Native​

Bei Verwendung von react-intl in React Native muss Ihre Laufzeitumgebung über integrierte Intl-Unterstützung verfügen (ähnlich der JSC International-Variante). Weitere Details finden Sie in diesen Issues:

React Native unter iOS​

Falls Sie die Intl-Variante von JSC nicht verwenden können (z.B. unter iOS), befolgen Sie die Anweisungen unter Laufzeitanforderungen, um diese APIs entsprechend zu polyfillen.

Das react-intl-Paket​

Installieren Sie das react-intl-npm-Paket via npm:

npm i -S react-intl

Das react-intl-npm-Paket stellt folgende Module bereit (Links von unpkg):

  • CommonJS: Ungebündelte Abhängigkeiten, "main" in package.json, Warnungen in Dev.

  • ES6: Ungebündelte Abhängigkeiten, "module" in package.json, Warnungen in Dev.

Modul-Bundler​

Wir haben React Intl für Modul-Bundler wie Browserify, Webpack oder Rollup optimiert, die React Intl für den Browser bündeln können:

  • Das "browser"-Feld in package.json ist so konfiguriert, dass beim Bündeln nur grundlegende englische Locale-Daten eingeschlossen werden. So werden beim Einsatz des "main"-Moduls in Node alle Locale-Daten geladen, im Browser-Build jedoch ignoriert.

  • Eine ES6-Version von React Intl wird als "jsnext:main" und "module" in package.json bereitgestellt und kann mit Rollup verwendet werden.

Entwicklungswarnungen sind in process.env.NODE_ENV !== 'production' eingebettet. Dies ermöglicht es, NODE_ENV beim Bundling und Minifizieren anzugeben, um diese Codeblöcke zu entfernen.

Das React Intl-Modul​

Egal, ob Sie die ES6-, CommonJS- oder UMD-Version von React Intl verwenden, alle bieten dieselben benannten Exporte:

react

Bei Verwendung der UMD-Version von React Intl ohne ein Modulsystem wird erwartet, dass react als globale Variable React existiert. Die oben genannten benannten Exporte werden dann in der globalen Variable ReactIntl platziert.

Erstellen eines I18n-Kontextes​

Nachdem React Intl und seine Lokalisierungsdaten geladen sind, kann ein I18n-Kontext für Ihre React-Anwendung erstellt werden.

React Intl verwendet das Provider-Pattern, um einen i18n-Kontext auf eine Komponenten-Hierarchie zu begrenzen. Dadurch können Konfigurationen wie das aktuelle Locale und übersetzte Zeichenfolgen/Nachrichten an der Wurzel der Komponenten-Hierarchie bereitgestellt und für die <Formatted*>-Komponenten verfügbar gemacht werden. Dies entspricht dem Konzept, das Flux-Frameworks wie Redux verwenden, um Zugriff auf einen Store innerhalb einer Komponenten-Hierarchie zu ermöglichen.

Alle Apps, die React Intl verwenden, müssen die <IntlProvider>-Komponente verwenden.

Die gängigste Verwendung besteht darin, Ihre Stamm-React-Komponente mit <IntlProvider> zu umschließen und sie mit dem aktuellen Gebietsschema des Benutzers und den entsprechenden übersetzten Zeichenketten/Nachrichten zu konfigurieren:

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

Siehe: Die <IntlProvider>-Dokumentation für weitere Details.

Daten formatieren​

React Intl bietet zwei Möglichkeiten, Daten zu formatieren: über React-Komponenten und seine API. Die Komponenten bieten eine idiomatische React-Art, Internationalisierung in eine React-App zu integrieren, und die <Formatted*>-Komponenten haben Vorteile gegenüber der direkten Verwendung der imperativen API. Die API sollte verwendet werden, wenn Ihre React-Komponente Daten in einen String-Wert formatieren muss, für den ein React-Element nicht geeignet ist; z.B. für ein title- oder aria-Attribut oder für Nebeneffekte in componentDidMount.

Auf die imperative API von React Intl wird über injectIntl zugegriffen, eine Higher-Order Component (HOC)-Factory. Sie umschließt die übergebene React-Komponente mit einer weiteren React-Komponente, die die imperative Formatierungs-API über die props an die umschlossene Komponente weitergibt. (Dies ähnelt dem Connect-to-Stores-Muster, das in vielen Flux-Implementierungen zu finden ist.)

Hier ein Beispiel, das <IntlProvider>, <Formatted*>-Komponenten und die imperative API verwendet, um einen I18n-Kontext einzurichten und Daten zu formatieren:

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

Angenommen, navigator.language ist "en-us":

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

Siehe: Die API-Dokumentation und die Komponenten-Dokumentation für weitere Details.

ESM-Build

react-intl und seine zugrundeliegenden Bibliotheken (@formatjs/icu-messageformat-parser, intl-messageformat, @formatjs/intl-relativetimeformat) exportieren ESM-Artefakte. Das bedeutet, dass Sie Ihre Build-Toolchain konfigurieren sollten, um diese Bibliotheken zu transpilieren.

Jest​

Fügen Sie transformIgnorePatterns hinzu, um diese Bibliotheken immer einzubeziehen, z.B:

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

webpack​

Wenn Sie babel-loader oder ts-loader verwenden, haben Sie folgende Optionen:

  1. Fügen Sie diese Bibliotheken in include ein:
{
  include: [
    path.join(__dirname, 'node_modules/react-intl'),
    path.join(__dirname, 'node_modules/intl-messageformat'),
    path.join(__dirname, 'node_modules/@formatjs/icu-messageformat-parser'),
  ]
}

ODER

  1. Fügen Sie diese Bibliotheken in exclude ein:
exclude: /node_modules\/(?!react-intl|intl-messageformat|@formatjs\/icu-messageformat-parser)/,

Kernkonzepte

  • Formatierer (Datum, Zahl, Nachricht, Relativzeit)

  • Provider und Injector

  • API und Komponenten

  • Nachrichtendeskriptor

  • Nachrichtensyntax

  • Standardnachrichten für die Extraktion definieren

  • Benutzerdefinierte benannte Formate

Beispielanwendungen

Dieses Git-Repo enthält mehrere ausführbare Beispiel-Apps. Diese eignen sich hervorragend, um React Intls Kernkonzepte in vereinfachten Anwendungen zu sehen.

API-Referenz

React Intl bietet mehrere API-Ebenen. Bei der Nutzung interagieren Sie mit Intl-Standards, der React Intl-API und React-Komponenten:

TypeScript-Nutzung

react-intl ist in TypeScript geschrieben und bietet daher erstklassige TS-Unterstützung.

Für die Nutzung von react-intl in TypeScript stellen Sie sicher, dass Ihre compilerOptions-lib-Konfiguration ["esnext.intl", "es2017.intl", "es2018.intl"] enthält.

Typisierung von Nachrichten-IDs und Locales​

Standardmäßig ist der Typ der id-Prop von <FormattedMessage> und formatMessage string. Sie können jedoch einen restriktiveren Typ festlegen, um Autovervollständigung und Fehlerprüfung zu erhalten. Überschreiben Sie dazu den folgenden globalen Namespace mit dem Union-Typ aller Ihrer Nachrichten-IDs:

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

Wobei messages das Objekt ist, das Sie normalerweise an <IntlProvider> übergeben würden, z.B.:

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

Sie können auch den folgenden Global überschreiben, um einen benutzerdefinierten Typ für Locale zu verwenden:

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

Typisierung benutzerdefinierter Formate​

Standardmäßig ist der Typ für die format-Prop von <FormattedDate>, <FormattedDateParts>, <FormattedTime> und <FormattedTimeParts> ein string. Das Gleiche gilt für die format-Konfiguration von formatDate, formatDateParts, formatTime und formatTimeParts. Sie können jedoch einen restriktiveren Typ festlegen, um Autovervollständigung und Fehlerprüfung zu erhalten. Überschreiben Sie dazu den folgenden globalen Namespace mit dem Union-Typ aller Ihrer benutzerdefinierten Formatnamen. Fügen Sie dazu folgenden Code an einer Stelle in Ihrem Code ein:

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

Dabei ist customFormats das Objekt, das Sie normalerweise an <IntlProvider> übergeben würden, und es könnte etwa so aussehen:

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

Fortgeschrittene Nutzung

Unsere Fortgeschrittene Nutzung bietet weitere Leitfäden für Produktionssetups in Umgebungen, wo Leistung entscheidend ist.

Unterstützte Tools

Nachrichtenextraktion​

Wir haben @formatjs/cli entwickelt, das beim Extrahieren von Nachrichten aus Dateien hilft. Es nutzt intern babel-plugin-formatjs und kann Nachrichten extrahieren, wenn Sie eine der folgenden Methoden verwenden:

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',
  })
}

ESLint-Plugin​

Wir haben auch eslint-plugin-formatjs entwickelt, das die Einhaltung spezifischer Regeln für Ihre Nachrichten erzwingt, falls Ihr Übersetzungsanbieter Einschränkungen hat.