Schnellstart

Überblick

Diese Schnellstartanleitung führt Sie durch die Internationalisierung Ihrer React-App mit gt-react.

Am Ende dieser Anleitung werden Sie eine vollständig internationalisierte React-App haben.

In dieser Anleitung werden wir die folgenden Punkte behandeln:

Installation

Konfiguration

Verwendung

Testen Ihrer App

Bereitstellung

Voraussetzungen

Ein React-Projekt mit einem unterstützten Framework (Next.js, Vite, etc.)
Grundkenntnisse in React und JavaScript

Installation

Installieren Sie die gt-react und gtx-cli Pakete:

npm i gt-react
npm i --save-dev gtx-cli

yarn add gt-react
yarn add --dev gtx-cli

bun add gt-react
bun add --dev gtx-cli

pnpm add gt-react
pnpm add --save-dev gtx-cli

Automatische Einrichtung: Wir haben einen experimentellen Setup-Assistenten, der Ihnen bei der Einrichtung Ihres Projekts mit gt-react helfen kann.

Probieren Sie ihn aus, indem Sie npx gtx-cli@latest ausführen. Sie müssen Strings immer noch manuell internationalisieren, aber er hilft Ihnen beim Einstieg.

Weitere Informationen finden Sie im Referenzhandbuch für den Setup-Assistenten.

Alternativ können Sie, wenn Sie möchten, dass Ihr KI-Tool wie Claude Code, Cursor oder Windsurf Ihr Projekt automatisch einrichtet, unseren mcp server verwenden.

Konfiguration

`GTProvider`

Das Herzstück von gt-react ist die GTProvider-Komponente.

Sie ist verantwortlich für:

Die Verwaltung der aktuellen Sprache des Benutzers
Die Bereitstellung relevanter Übersetzungen für Ihre Anwendung
Die Bereitstellung eines Kontexts für Hooks zum Zugriff auf Übersetzungen
Die Bereitstellung eines Kontexts für Hooks zum Ändern der Sprache des Benutzers

Fügen Sie zunächst die GTProvider-Komponente zu Ihrer Anwendung hinzu. Sie sollte so weit oben wie möglich im Komponentenbaum platziert werden.

src/App.tsx

import { GTProvider } from 'gt-react';

export default function App() {
  return (
    <GTProvider>
      <App />
    </GTProvider>
  );
}

Erstellen Sie als Nächstes eine gt.config.json-Datei im Root-Verzeichnis Ihres Projekts. Diese Datei wird sowohl zur Konfiguration des gtx-cli-Tools als auch der gt-react-Bibliothek verwendet.

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}

Sie sollten defaultLocale und locales an Ihr Projekt anpassen. Eine Liste der unterstützten Sprachen finden Sie für weitere Informationen.

Zuletzt geben Sie die gt.config.json-Datei als Props an den Provider weiter.

import gtConfig from './gt.config.json';

<GTProvider {...gtConfig}>
  <App />
</GTProvider>

Das Weitergeben der gt.config.json-Datei sorgt für eine konsistente Konfiguration in Ihrer gesamten Anwendung und im CLI-Tool.

Alternativ können Sie auch jede Prop einzeln in der GTProvider-Komponente angeben.

<GTProvider
  defaultLocale="en"
  locales={["fr", "es"]}
>

Umgebungsvariablen

Setzen Sie die folgenden Umgebungsvariablen:

VITE_GT_API_KEY="" # Ihr General Translation Developer API-Schlüssel
VITE_GT_PROJECT_ID="" # Ihre General Translation Projekt-ID

GATSBY_GT_API_KEY="" # Ihr General Translation Developer API-Schlüssel
GATSBY_GT_PROJECT_ID="" # Ihre General Translation Projekt-ID

REDWOOD_ENV_GT_API_KEY="" # Ihr General Translation Developer API-Schlüssel
REDWOOD_ENV_PROJECT_ID="" # Ihre General Translation Projekt-ID

NEXT_PUBLIC_GT_API_KEY="" # Ihr General Translation Developer API-Schlüssel
NEXT_PUBLIC_GT_PROJECT_ID="" # Ihre General Translation Projekt-ID

REACT_APP_GT_API_KEY="" # Ihr General Translation Developer API-Schlüssel
REACT_APP_GT_PROJECT_ID="" # Ihre General Translation Projekt-ID

Viele React-Frameworks haben jeweils eine eigene Methode, Umgebungsvariablen an den Client zu exportieren. In Entwicklungsumgebungen müssen sowohl GT_API_KEY als auch GT_PROJECT_ID an den Client exportiert werden.

Wir haben bisher Unterstützung für einige Bibliotheken hinzugefügt, aber bitte teilen Sie uns mit, falls Ihr Framework nicht aufgeführt ist, indem Sie ein Issue in unserem GitHub-Repository erstellen.

Stellen Sie sicher, dass Ihre API-Schlüssel-Variable nur in Ihrer Entwicklungsumgebung gesetzt ist! Sie sollte nicht in der Produktion gesetzt werden.

Sie können einen kostenlosen API-Schlüssel und eine Projekt-ID erhalten, indem Sie ein General Translation-Konto erstellen.

Nachdem Sie ein Konto erstellt haben, navigieren Sie zur Seite Development API Keys, um Ihren Dev API-Schlüssel und Ihre Projekt-ID zu erhalten.

Alternativ können Sie auch den CLI-Tool-Befehl npx gtx-cli auth verwenden, um einen API-Schlüssel und eine Projekt-ID für Ihr Projekt zu generieren, die in Ihrer .env.local-Datei gespeichert werden.

Verwendung

Super! Wenn du die obigen Schritte befolgt hast, ist dein React-Projekt jetzt so eingerichtet, dass es gt-react verwenden kann.

Der nächste Schritt ist, deine Inhalte zu internationalisieren. Hier geben wir einen kurzen Überblick über die verschiedenen Möglichkeiten, Inhalte in deiner Anwendung zu übersetzen.

`<T>` Komponente

Die <T> Komponente ist die Hauptkomponente zum Übersetzen von JSX-Inhalten in deiner Anwendung.

Um sie zu verwenden, wickle einfach das JSX, das du übersetzen möchtest, in die <T> Komponente.

import { T } from 'gt-react';
<T>
  <div>Dein Inhalt</div>
</T>

Wenn du dynamische Inhalte hast, musst du Variable-Komponenten verwenden, um die dynamischen Werte zu übergeben.

import { T, Var } from 'gt-react';

<T>
  <div>Hallo, <Var>{name}</Var>!</div>
</T>

Siehe den JSX übersetzen Leitfaden für weitere Informationen.

`useGT` Hook

Der useGT Hook ist ein React-Hook, der eine Funktion zurückgibt, mit der Zeichenketten übersetzt werden können.

import { useGT } from 'gt-react';

const translate = useGT();
translate('Hello, world!');

Siehe den Zeichenketten übersetzen Leitfaden für weitere Informationen.

Die Nutzung der Hot-Reload-Übersetzungsfunktionalität ist hilfreich, um deine Anwendung zu internationalisieren.

Um dies zu aktivieren, stelle sicher, dass du die Umgebungsvariablen GT_API_KEY und GT_PROJECT_ID in deiner Entwicklungsumgebung gesetzt hast.

Testen Ihrer App

Herzlichen Glückwunsch! 🥳 Wenn Sie die obigen Schritte befolgt haben, ist Ihre App jetzt mehrsprachig! Sehen wir uns das Ganze in Aktion an.

Ihre App in einer anderen Sprache anzeigen

Fügen Sie die <LocaleSelector> Komponente zu Ihrer App hinzu. Damit können Sie eine andere Sprache für Ihre App auswählen.

Tipp: Sie können diesen Schritt auch überspringen und einfach die Sprache in Ihren Browsereinstellungen ändern.

Starten Sie Ihre React-App im Entwicklungsmodus.

npm run dev

yarn run dev

bun run dev

pnpm run dev

Öffnen Sie Ihre App in Ihrem bevorzugten Browser (in der Regel unter http://localhost:3000).

Fehlerbehebung

Deployment

Super! Wenn Sie mit Ihren Übersetzungen und der Funktionalität Ihrer App zufrieden sind, können Sie Ihre Anwendung jetzt bereitstellen.

Das Verhalten von gt-react in der Produktion unterscheidet sich leicht von der Entwicklung. Insbesondere werden zur Laufzeit keine Übersetzungen mehr durchgeführt.

Das bedeutet, dass Sie Ihre Inhalte vor der Bereitstellung Ihrer Anwendung, also im Build-Prozess, übersetzen müssen.

Glücklicherweise verfügt das Tool gtx-cli über einen Befehl translate, mit dem Sie Ihre Inhalte automatisch übersetzen lassen können.

Zuerst benötigen Sie einen Production API-Schlüssel von der General Translation platform.

Bitte beachten Sie, dass sich dieser Schlüssel von Ihrem Development API-Schlüssel unterscheidet und mit gtx-api- beginnt, anstatt mit gtx-dev-.

Lesen Sie mehr über den Unterschied zwischen Development- und Production-Schlüsseln hier.

Fügen Sie diese Umgebungsvariable zu Ihrer CI/CD-Pipeline hinzu.

GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>

Stellen Sie sicher, dass GT_API_KEY NICHT mit NEXT_PUBLIC_ oder VITE_ (je nach Framework) versehen ist!

Andernfalls riskieren Sie, Ihren API-Schlüssel öffentlich zugänglich zu machen.

Führen Sie den Befehl translate aus, um Ihre Inhalte zu übersetzen.

npx gtx-cli translate

Sie können das Verhalten des Befehls translate mit der Datei gt.config.json konfigurieren.

Weitere Informationen finden Sie im Referenzhandbuch zum CLI Tool.

Fügen Sie den Befehl translate zu Ihrem Build-Prozess hinzu.

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Zusammenfassung

In diesem Leitfaden haben wir behandelt, wie Sie Ihr React-Projekt mit gt-react einrichten
Wir haben kurz die verschiedenen Möglichkeiten behandelt, Inhalte in Ihrer Anwendung zu übersetzen.
Wir haben auch behandelt, wie Sie Ihre Anwendung bereitstellen, nachdem Sie Ihre Inhalte internationalisiert haben.

Nächste Schritte

Erfahren Sie, wie Sie JSX-Inhalte mit der <T>-Komponente übersetzen: JSX übersetzen
Erfahren Sie, wie Sie Strings mit dem useGT-Hook übersetzen: Strings übersetzen
Erfahren Sie, wie Sie lokale Übersetzungen verwenden: Lokale Übersetzungen

Schnellstart

Was ist, wenn ich die General Translation Plattform nicht verwenden möchte?

Die Sprache meiner App ändert sich nicht, obwohl ich die Sprache meines Browsers geändert habe.

Warum dauert es so lange, bis neue Sprachen geladen werden?

Warum werden manche Dinge übersetzt und andere nicht?

Warum sind einige Übersetzungen ungenau?

What if I'm not using the General Translation platform?

Auf dieser Seite