Jak używać React Intl do internacjonalizacji aplikacji React

React Intl to popularna biblioteka, która oferuje zbiór komponentów i narzędzi umożliwiających internacjonalizację aplikacji tworzonych w React. Proces internacjonalizacji, często skracany do i18n, polega na dostosowaniu aplikacji tak, aby były dostępne i zrozumiałe dla użytkowników posługujących się różnymi językami i pochodzących z odmiennych kultur.

Dzięki ReactIntl możesz bez problemu wdrożyć obsługę wielu języków i dostosować swoją aplikację do różnych lokalizacji geograficznych.

Instalacja React Intl

Aby rozpocząć korzystanie z biblioteki React Intl, niezbędna jest jej wcześniejsza instalacja. Możesz to zrobić za pomocą jednego z kilku popularnych menedżerów pakietów, takich jak npm, yarn czy pnpm.

W celu zainstalowania biblioteki za pomocą npm, wprowadź w terminalu poniższą komendę:

 npm install react-intl

Jeśli natomiast preferujesz yarn, użyj następującego polecenia:

 yarn add react-intl

Sposób użycia biblioteki React Intl

Po pomyślnej instalacji React Intl, możesz zacząć korzystać z jej komponentów i funkcji w swojej aplikacji. React Intl w dużej mierze bazuje na funkcjonalnościach dostępnych w JavaScript Intl API.

Wśród komponentów oferowanych przez React Intl, na szczególną uwagę zasługują FormattedMessage oraz IntlProvider.

Komponent FormattedMessage jest odpowiedzialny za wyświetlanie przetłumaczonych tekstów w aplikacji, natomiast IntlProvider dostarcza niezbędne dane dotyczące tłumaczeń i formatowania.

Zanim zaczniesz korzystać z komponentów FormattedMessage i IntlProvider do translacji Twojej aplikacji, musisz przygotować plik z tłumaczeniami. W pliku tym znajdują się wszystkie tłumaczenia wykorzystywane w aplikacji. Możesz stworzyć oddzielne pliki dla każdego języka i lokalizacji, lub też skorzystać z jednego, w którym zgromadzisz wszystkie tłumaczenia.

Przykładowo:

 export const messagesInFrench = {
    greeting: "Bonjour {name}"
}
  
export const messagesInItalian = {
    greeting: "Buongiorno {name}"
}

W tym przykładowym pliku tłumaczeń mamy dwa obiekty: messageInFrench i messageInItalian. W tekście powitania, element {name} może zostać dynamicznie zastąpiony odpowiednią wartością w trakcie działania aplikacji.

Aby móc korzystać z tłumaczeń w aplikacji, główny komponent aplikacji należy opakować komponentem IntlProvider. Komponent IntlProvider wymaga trzech właściwości: locale, defaultLocale i messages.

Właściwość locale przyjmuje wartość string, która określa preferowaną lokalizację użytkownika, natomiast defaultLocale definiuje ustawienia domyślne, jeśli preferowana lokalizacja użytkownika nie jest dostępna. Właściwość message akceptuje obiekt z tłumaczeniami.

Poniżej znajduje się przykład użycia IntlProvider:

 import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { IntlProvider } from "react-intl";
import { messagesInFrench } from "./translation";
ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <IntlProvider locale="fr" messages={messagesInFrench} defaultLocale="en">
      <App />
    </IntlProvider>
  </React.StrictMode>
);
 

W przedstawionym przykładzie, do komponentu IntlProvider przekazywane są: ustawienia regionalne „fr”, tłumaczenia dla języka francuskiego oraz domyślne ustawienia regionalne „en”.

Istnieje możliwość przekazania wielu obiektów lokalizacji lub tłumaczeń. IntlProvider automatycznie wykryje język przeglądarki użytkownika i wykorzysta właściwe tłumaczenia.

Aby wyświetlić przetłumaczone teksty w aplikacji, należy użyć komponentu FormattedMessage. Komponent FormattedMessage przyjmuje właściwość id, która odpowiada identyfikatorowi wiadomości w obiekcie wiadomości.

Komponent obsługuje także właściwości defaultMessage oraz values. Właściwość defaultMessage definiuje tekst zastępczy, jeżeli tłumaczenie nie jest dostępne dla bieżącej lokalizacji, natomiast właściwość values umożliwia dynamiczne wstawianie wartości w przetłumaczonych wiadomościach.

Przykładowo:

 import React from "react";
import { FormattedMessage } from "react-intl";
function App() {
  return (
    <div>
      <p>
        <FormattedMessage
          id="greeting"
          defaultMessage="Good morning {name}"
          values={{ name: 'John'}}
        />
      </p>
    </div>
  );
}
export default App;
 

W powyższym kodzie, właściwość id komponentu FormattedMessage odwołuje się do klucza powitania z obiektu messageInFrench, a właściwość values zastępuje symbol zastępczy {name} wartością „John”.

Formatowanie liczb przy użyciu komponentu FormattedNumber

React Intl dostarcza również komponent FormattedNumber, który umożliwia formatowanie liczb zgodnie z bieżącymi ustawieniami regionalnymi. Komponent akceptuje różne atrybuty pozwalające na dostosowanie formatowania, takie jak styl, waluta, a także minimalna i maksymalna ilość miejsc po przecinku.

Oto kilka przykładów:

 import React from "react";
import { FormattedNumber } from "react-intl";
function App() {
  return (
    <div>
      <p>
        Decimal: <FormattedNumber value={123.456} style="decimal" />
      </p>
      <p>
        Percent: <FormattedNumber value={123.456} style="percent" />
      </p>
    </div>
  );
}
export default App;
 

W przedstawionym przykładzie, komponent FormattedNumber przyjmuje wartość, którą chcemy sformatować.

Poprzez użycie atrybutu style, możemy spersonalizować wygląd sformatowanej liczby. Wartość atrybutu style może być ustawiona na „decimal”, „percent” lub „currency”.

Kiedy właściwość style zostanie ustawiona na „currency”, komponent FormattedNumber formatuje liczbę jako wartość waluty, wykorzystując kod waluty określony w atrybucie currency:

 import React from "react";
import { FormattedNumber } from "react-intl";
function App() {
  return (
    <div>
      <p>
        Price: <FormattedNumber value={123.456} style="currency" currency="USD" />
      </p>
    </div>
  );
}
export default App;
 

W powyższym przykładzie, komponent FormattedNumber formatuje liczbę z wykorzystaniem stylu waluty i kodu waluty USD.

Liczby mogą być formatowane również z określoną liczbą miejsc po przecinku, z użyciem atrybutów minimumFractionDigits oraz maximumFractionDigits.

Atrybut minimumFractionDigits określa minimalną liczbę cyfr po przecinku, która ma zostać wyświetlona. Natomiast atrybut maximumFractionDigits określa maksymalną liczbę cyfr po przecinku.

Jeżeli liczba posiada mniej cyfr po przecinku, niż zostało zdefiniowane w minimumFractionDigits, React Intl dopełni ją zerami. Jeżeli liczba posiada więcej cyfr po przecinku, niż zostało zdefiniowane w maximumFractionDigits, biblioteka zaokrągli liczbę.

Poniżej znajduje się przykład, który pokazuje, jak użyć tych atrybutów:

 import React from "react";
import { FormattedNumber } from "react-intl";
function App() {
  return (
    <div>
      <p>
        <FormattedNumber
          value={123.4567}
          minimumFractionDigits={2}
          maximumFractionDigits={3}
        />
      </p>
    </div>
  );
}
export default App;
 

Formatowanie dat za pomocą komponentu FormattedDate

Dzięki React Intl, formatowanie dat jest proste, spójne i czytelne. Komponent FormattedDate oferuje łatwy i skuteczny sposób formatowania dat. Działa podobnie do bibliotek formatujących daty, takich jak np. Moment.js.

Komponent FormattedDate przyjmuje wiele atrybutów, takich jak value, day, month oraz year. Właściwość value akceptuje datę, którą chcemy sformatować, natomiast pozostałe atrybuty konfigurują jej formatowanie.

Przykładowo:

 import React from "react";
import { FormattedDate } from "react-intl";
function App() {
  const today = new Date();
  return (
    <div>
      <p>
        Today's date is
        <FormattedDate
          value={today}
          day="numeric"
          month="long"
          year="numeric"
        />
      </p>
    </div>
  );
}
export default App;
 

W tym przykładzie, atrybut value przyjmuje aktualną datę. Poprzez atrybuty day, month oraz year określamy, że rok, miesiąc i dzień mają być wyświetlane w pełnej formie.

Oprócz day, month oraz year, dostępne są również inne atrybuty, które pozwalają na formatowanie daty. Oto atrybuty oraz ich możliwe wartości:

• year: „numeric”, „2-digit”
• month: „numeric”, „2-digit”, „narrow”, „short”, „long”
• day: „numeric”, „2-digit”
• hour: „numeric”, „2-digit”
• minute: „numeric”, „2-digit”
• second: „numeric”, „2-digit”
• timeZoneName: „short”, „long”

Możesz również użyć komponentu FormattedDate, aby sformatować i wyświetlić czas:

 import React from "react";
import { FormattedDate } from "react-intl";
function App() {
  const today = new Date();
  return (
    <div>
      <p>
        The time is
        <FormattedDate
          value={today}
          hour="numeric"
          minute="numeric"
          second="numeric"
        />
      </p>
    </div>
  );
}
export default App;
 

Internacjonalizacja aplikacji React dla szerszej grupy odbiorców

W tym artykule dowiedziałeś się, jak zainstalować i skonfigurować bibliotekę React-Intl w aplikacji React. React-intl znacząco upraszcza formatowanie liczb, dat i walut w aplikacji React. Za pomocą komponentów FormattedMessage, FormattedNumber i FormattedDate możesz formatować dane, w oparciu o ustawienia regionalne użytkownika.

Programiści React często popełniają błędy, które mogą prowadzić do poważnych konsekwencji. Przykładem jest niepoprawne aktualizowanie stanu. Ważne jest, aby być świadomym tych powszechnych błędów i naprawiać je we wczesnej fazie rozwoju, aby uniknąć potencjalnych, kosztownych problemów.