INTEGRTR Translation Hub: Ihre React-App internationalisieren

In Organisationen, die an Anwendungen für ein weltweites Publikum arbeiten, ist es eine grundlegende Anforderung, die Nutzer in mehreren Sprachen zu bedienen. Der Prozess, diese mehrsprachige Nutzung zu unterstützen, heißt Internationalisierung (i18n).

Für viele dieser Organisationen kann Internationalisierung kein nachträglicher Gedanke sein, sondern ist fester Bestandteil des Entwicklungsprozesses. Dennoch kann die Umsetzung mühsam sein, denn Entwickler kennen womöglich nicht alle Sprachen, in die ihre Anwendung übersetzt werden soll. Selbst mit Übersetzungswerkzeugen wie Google Translate ist es aufwendig, sämtliche Textinhalte einer Anwendung manuell zu übersetzen. Darüber hinaus wird es schwierig, Rückmeldungen von nicht-technischen Nutzern einzuholen, wenn die Sprachdateien gemeinsam mit dem Quellcode üblicherweise in GitHub eingecheckt sind.

Wir bei INTEGRTR bauen ERP-Software, die weltweit eingesetzt wird. Internationalisierung war daher schon immer ein wichtiger Teil unseres Entwicklungsprozesses, und wir standen vor denselben Problemen. Um sie zu lösen und Internationalisierung für uns einfacher zu machen, haben wir eine Lösung entwickelt, und nun sind wir bereit, sie in die Welt zu tragen. Wir nennen sie INTEGRTR Translation Hub, unsere zentrale Anlaufstelle, um all unsere Anwendungen im Handumdrehen zu internationalisieren! Der Translation Hub vereinfacht maschinell erzeugte Übersetzungen, hilft beim Verwalten manueller Übersetzungen und hält Ihre Übersetzungen mit Ihrem Versionskontrollsystem wie Git synchron.

In diesem Beitrag sehen wir uns an, wie wir Internationalisierung in einer React-App einrichten und wie wir den INTEGRTR Translation Hub nutzen, um die Übersetzungen unserer Anwendung zu verwalten. Dafür brauchen wir aber zunächst eine Anwendung.

Um die Internationalisierungsfunktionen des Translation Hub zu zeigen, haben wir ein minimalistisches Spiel in React gebaut. Bevor wir tiefer in Internationalisierung und den Translation Hub einsteigen, gehen wir das Spiel kurz durch.

Hinweis: Dieser Beitrag behandelt nur die Einrichtung von Internationalisierung in einer React-App und wie wir den INTEGRTR Translation Hub nutzen, um die App zu übersetzen. Die Logik des Spiels wird hier nicht erklärt.

Hier ein kleiner Einblick in das Spiel. Bunt, oder? Hier spielen.

Das Spiel heißt ColorShuffle. Es zu spielen ist wirklich einfach! Sie müssen lediglich die Kreise in der zweiten Reihe durch Klicken oder Tippen drehen und den oberen Quadranten des Kreises mit der darüber angezeigten Farbe in Übereinstimmung bringen. Jedes Mal, wenn Sie auf einen Kreis klicken oder tippen, drehen sich auch die benachbarten Kreise. Um zu gewinnen, müssen Sie nur alle oberen Quadranten der Kreise mit der jeweils darüber angezeigten Farbe zur Deckung bringen, und das mit möglichst wenigen Drehungen. Das ist ColorShuffle.

Wenn Sie einen Blick auf den Quellcode des Spiels werfen möchten, tauchen Sie gern in das GitHub-Repo ein.

Richten wir Internationalisierung in unserer App ein!

Jetzt, wo wir wissen, was Internationalisierung ist, und die App gesehen haben, die wir bauen, sprechen wir darüber, wie wir sie mit React Intl in unserer Anwendung einrichten.

Einführung in React Intl

React Intl ist Teil von FormatJS, einer Sammlung von JavaScript-Bibliotheken zur Internationalisierung. Diese Bibliothek stellt uns React-Komponenten und APIs bereit, die uns bei der Internationalisierung von Strings, Datumsangaben und Währungen helfen.

Mehr über react-intl lesen Sie hier

Installation

Wir können die Bibliothek react-intl mit einem Paketmanager wie yarn oder npm installieren

yarn add react-intl

Hinweis: Ich verwende in diesem Artikel yarn für unsere Paketverwaltung, Sie können aber ebenso npm nutzen. Ersetzen Sie einfach yarn durch die entsprechenden npm-Befehle.

Einrichtung

Als Erstes müssen wir im Ordner /src einen Ordner namens intl anlegen (Sie können ihn auch im Root-Ordner ablegen, wenn Ihnen das lieber ist) und darin eine Standarddatei namens i18n.json oder i18n_en.json ergänzen.

Sie können statt i18n auch ein eigenes Präfix verwenden

// i18n.json

{
    "COLOR": "Color",
    "SHUFFLE": "Shuffle"
}

In diese Standarddatei kommen die Schlüssel-Wert-Paare für alle Textinhalte unserer App.

Sobald unsere Standarddatei steht, importieren wir sie in App.jsx und legen einen State an, der die Locale verwaltet.

// App.jsx

import {IntlProvider} from 'react-intl'

const selectedMessages = (lang) => {
  switch (lang) {
    // we will add cases for other languages 
    // as and when we add the i18n files for them
    default:
      return en;
  }
};

export default function App() {
  const lang = window.location.pathname.split('/')[1];

  const [locale, setLocale] = useState({
    selectedLang: lang ? lang : 'en',
    messages: lang ? selectedMessages(lang) : en,
  });

  return (
    <IntlProvider locale={locale.selectedLang} messages={locale.messages}>
      <div className="container">
        <GameName />
        <Game />
        <Options appLangs={appLangs} locale={locale} updateLocaleState={updateLocaleState} />
        <ExternalLink />
      </div>
    </IntlProvider>
  );
}

lang ist die Sprache, die wir aus der URL holen. Gibt die URL eine Sprache an, verwenden wir genau diese Sprache und legen sie in der Eigenschaft selectedLang unseres States ab. selectedMessages() ist eine Funktion, die uns das Message-Objekt für die als Argument übergebene Sprache zurückgibt.

Sobald der State steht, kann es losgehen...

React Intl stellt uns einen Internationalization Context Provider namens <IntlProvider> bereit. Wir müssen unsere Anwendung lediglich mit diesem Provider umschließen. Indem wir unsere Anwendung mit <IntlProvider> umschließen, machen wir den Internationalisierungs-Kontext für alle React-Komponenten der Anwendung verfügbar.

Wie Sie im Code oben sehen, übergeben wir zwei Props an <IntlProvider>:

1. locale: locale ist die aktuelle Sprache, in die unsere Anwendung übersetzt werden soll.
2. messages: enthält alle übersetzten Strings zur ausgewählten Sprache.

Auf Basis der übergebenen Props reicht <IntlProvider> den nötigen Kontext an alle darin umschlossenen Komponenten weiter und übersetzt die App.

Die Standardsprachdatei liegt nun vor, der Internationalization Context Provider ist eingerichtet. Der nächste Schritt ist also, alle Textinhalte in unserer App zu finden und sie mit <FormattedMessage> zu umschließen.

// GameName.jsx

import React from 'react';
import { FormattedMessage } from 'react-intl';

export function GameName() {
  return (
    <div className="game-title">
      <span>
        <FormattedMessage id="COLOR" />
      </span>
      <span>
        <FormattedMessage id="SHUFFLE" />
      </span>
    </div>
  );
}

In der Komponente <FormattedMessage> übergeben wir eine id, den Schlüssel zu dem übersetzten String (Schlüssel-Wert-Paare in der Sprachdatei), den wir dort verwenden möchten. Das müssen wir für sämtliche Textinhalte unserer Anwendung tun, und das war's, die Einrichtung ist abgeschlossen! Wir pushen den gesamten Code in unser GitHub-Repo.

Hinweis: Der INTEGRTR Translation Hub ist eng mit GitHub verzahnt, denn derzeit lassen sich nur Repos von GitHub hinzufügen!

Nachdem wir die Internationalisierung eingerichtet haben, sehen wir, dass wir bislang nur die Sprachdatei für Englisch haben. Wir wollen aber auch weitere Sprachen unterstützen.

Wie ich zu Beginn des Beitrags erwähnt habe, kennt ein Entwickler womöglich nicht alle Sprachen, und all diese Übersetzungen manuell in die App einzupflegen ist eine langwierige Arbeit. Und genau hier kommt der INTEGRTR Translation Hub zur Rettung!

Auftritt INTEGRTR Translation Hub!

Der INTEGRTR Translation Hub ist eine Anwendung, die dafür gebaut ist, unsere GitHub-Projekte im Handumdrehen zu übersetzen. Er unterstützt private wie öffentliche Repositories und IST AUSSERDEM KOSTENLOS NUTZBAR!

Mehr über den INTEGRTR Translation Hub erfahren Sie in seinem FAQ-Bereich

Nun stellt sich die Frage: Wie nutzen wir den INTEGRTR Translation Hub, um unsere GitHub-Projekte zu übersetzen?

Den INTEGRTR Translation Hub zu nutzen ist ein Kinderspiel. Ich führe Sie durch die Schritte.

1. Besuchen Sie den INTEGRTR Translation Hub : https://translate.integrtr.com

Wenn Sie auf den Link klicken, gelangen Sie zur Landingpage des Translation Hub. Wie die Landingpage aussieht, sehen Sie im Bild unten.

2. Anmelden oder registrieren

Wenn Sie noch kein Konto haben, können Sie entweder über den Link "Sign Up" ein Konto anlegen oder sich mit Ihrem Google-Konto anmelden. Nach der Registrierung erhalten Sie eine Bestätigungs-E-Mail. Nach der Bestätigung werden Sie zur Anmeldeseite weitergeleitet, wo Sie Ihre Zugangsdaten eingeben und sich an der Anwendung anmelden.

So sieht der Hauptbildschirm der App aus:

3. Projekt hinzufügen

Um mit der Übersetzung unserer Anwendung zu beginnen, müssen wir über "Add Project" ein Projekt hinzufügen. Danach melden wir uns mit unserem GitHub-Konto an und sehen den folgenden Bildschirm:

Als Nächstes erlauben wir dem translation-assistant den Zugriff auf unsere Repositories. Das geht über die Schaltfläche "Configure on GitHub", die uns zu einer GitHub-Seite weiterleitet, auf der wir die Repositories autorisieren, die er kennen soll.

Wenn Sie schon einmal CI/CD- oder Deployment-Werkzeuge mit GitHub integriert haben, dürfte Ihnen dieser Ablauf vertraut vorkommen.

Nach der Installation des translation-assistant sehen wir, dass unsere Repositories nun im Translation Hub aufgelistet sind.

4. Konfiguration

Klicken Sie auf das Repository, das Sie übersetzen möchten, und Sie werden zur folgenden Seite weitergeleitet:

Hier wählen wir zuerst im Feld Branch den Hauptbranch unseres GitHub-Repos. Im Feld New Project Name vergeben wir den Namen unseres Übersetzungsprojekts.

Anschließend tragen wir im Feld Translations Path den Pfad des Ordners ein, in dem all unsere Sprachdateien liegen (bei mir ist das src/intl/ ).

Im Feld Source Type wählen wir den Quelltyp unserer Datei, also ob es sich um eine .json- oder eine .properties-Datei handelt.

Danach wählen wir das Translation File Prefix, das wir in unseren Sprachdateien verwendet haben (all meine Sprachdateien sind mit dem Präfix i18n gespeichert: i18n.json).

Zuletzt wählen wir die Sprachen aus, in die unsere App übersetzt werden soll. Sind all diese Schritte erledigt, klicken Sie auf Next und lassen den Translation Hub zaubern!

Hinweis: Ihre Dateien sind womöglich nicht mit dem Präfix i18n gespeichert. Wählen Sie in diesem Fall die Option custom und tragen Sie das Präfix ein, das Sie in Ihren Dateien verwendet haben.

5. Übersetzung

Nachdem die Konfiguration steht, geht es an die Übersetzung unserer App. Auf der Seite oben passiert die ganze Magie! Wir können die Übersetzungen entweder manuell oder automatisch ergänzen.

Manuell tippen wir den übersetzten Text einfach in die Textfelder. Automatisch geht es, indem Sie bei jedem Text einzeln auf die Schaltfläche Translate klicken.

Oder Sie klicken oben rechts auf die Schaltfläche Translate All, um alle Texte auf einmal zu übersetzen.

Sobald wir alle Texte übersetzt haben, speichern wir die Übersetzungen über die Schaltfläche Save unten rechts auf dem Bildschirm.

Falls Sie bei der Übersetzung Ihrer Anwendungen mit jemandem zusammenarbeiten möchten, klicken Sie auf die Schaltfläche "Customize" und tragen die E-Mail-Adressen der Nutzer, die Sie hinzufügen möchten, im Feld Project Members ein. Damit erhalten sie eine Einladung, den Translation Hub zu nutzen, und Sie können gemeinsam mit Ihrem Team an der Übersetzung Ihrer Anwendung arbeiten.

6. Integration

Nachdem wir alle Texte unserer Anwendung in die gewünschten Sprachen übersetzt haben, ist es an der Zeit, sie in unsere Anwendung zu integrieren. Dafür gibt es zwei Wege:

• Die Dateien exportieren
• Einen PR erstellen (der einfachste Weg)

Oben rechts sehen Sie drei senkrechte Punkte. Klicken Sie darauf, und Sie sehen zwei Optionen: Export und Create PR.

Mit der Option Export laden Sie eine .zip-Datei herunter, die all Ihre übersetzten Sprachen enthält und die Sie in den Übersetzungsordner Ihrer Anwendung entpacken können.

Mit der Option Create PR wird in Ihrem GitHub-Repo ein PR mit allen Änderungen erstellt. Sie können den PR genehmigen, er wird in Ihren Master gemergt, und voilà: Ihre Übersetzungsdateien sind nun Teil Ihrer Anwendung!

Das Bild oben zeigt, wie der PR aussehen wird. Sie müssen ihn lediglich mit Ihrem Hauptbranch mergen, und schon kann es losgehen.

Sobald die Übersetzungsdateien da sind, können Sie sie in App.jsx importieren, sie der Funktion selectedMessages hinzufügen und mit der Logik für die Sprachauswahl weitermachen.

// App.jsx

function mergeWithDefault(messages) {
  return {
    ...en,
    ...messages,
  };
}

const selectedMessages = (lang) => {
  switch (lang) {
    case 'de':
      return mergeWithDefault(de);
    case 'bn':
      return mergeWithDefault(bn);
    case 'hi':
      return mergeWithDefault(hi);
    case 'kn':
      return mergeWithDefault(kn);
    case 'en':
    default:
      return en;
  }
};

Die Funktion mergeWithDefault führt die ausgewählte Sprache mit der Standardsprache zusammen, also mit Englisch. Das verhindert, dass die Anwendung bricht, falls einzelne Übersetzungen der ausgewählten Sprache fehlen.

Sind die übersetzten Strings der ausgewählten Sprache nicht verfügbar, zeigt die App die englische Variante des Textes, da wir die ausgewählte Sprache mit Englisch zusammenführen.

Nun können Sie Übersetzungen bequem aktualisieren, ergänzen oder entfernen. Wenn Sie Änderungen an bestehenden Sprachen vornehmen, müssen Sie dafür nicht einmal zusätzlichen Code schreiben. Von der Übersetzung bis zur PR-Erstellung übernimmt das alles der Translation Hub.

Fazit

Mehrsprachige Anwendungen sind nicht einfach zu bauen, aber mit Werkzeugen wie dem INTEGRTR Translation Hub möchten wir den Prozess einfacher machen. Probieren Sie den INTEGRTR Translation Hub aus und machen Sie Ihre React-App weltweit zugänglich.