Bringe deine React-App in wenigen Minuten zum Übersetzen.

Voraussetzungen: React, grundlegende JavaScript-Kenntnisse

Installation

Installiere die Pakete „gt-react“ und „gtx-cli“:

npm i gt-react
npm i 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

Konfiguration

GTProvider

Die Komponente GTProvider stellt Ihren React-Komponenten einen Übersetzungskontext bereit. Sie verwaltet den Locale-Status, die Übersetzungen und ermöglicht die Hooks useGT und useTranslations.

Fügen Sie den GTProvider zu Ihrer Root-App-Komponente hinzu:

import { GTProvider } from 'gt-react';

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

Erstellen Sie im Projektstammverzeichnis die Datei gt.config.json:

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

Passen Sie die locales für Ihr Projekt an. Siehe supported locales für options.

Umgebungsvariablen

Fügen Sie Folgendes zu Ihrer Umgebungsdatei hinzu, um Hot-Reloading während der Entwicklung zu aktivieren:

VITE_GT_API_KEY="your-dev-api-key"
VITE_GT_PROJECT_ID="your-project-id"

REACT_APP_GT_API_KEY="your-dev-api-key"
REACT_APP_GT_PROJECT_ID="your-project-id"

GATSBY_GT_API_KEY="your-dev-api-key"
GATSBY_GT_PROJECT_ID="your-project-id"

REDWOOD_ENV_GT_API_KEY="your-dev-api-key"
REDWOOD_ENV_GT_PROJECT_ID="your-project-id"

Holen Sie sich kostenlose API-Schlüssel unter dash.generaltranslation.com oder führen Sie Folgendes aus:

npx gtx-cli auth

Verwendung

Jetzt können Sie mit der Internationalisierung Ihrer Inhalte beginnen. Es gibt zwei Hauptansätze:

JSX-Inhalte mit <T>

Umschließe JSX-Elemente, um sie mit der Komponente <T> zu übersetzen:

import { T } from 'gt-react';

function Welcome() {
  return (
    <T>
      <h1>Willkommen in unserer App!</h1>
    </T>
  );
}

Für dynamische Inhalte verwenden Sie Variablenkomponenten wie <Var>:

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

function Greeting({ user }) {
  return (
    <T>
      <p>Hallo, <Var>{user.name}</Var>!</p>
    </T>
  );
}

Siehe den Leitfaden zur Verwendung der Komponente <T> für weitere Informationen.

Einfache Strings mit useGT

Für Attribute, Beschriftungen und einfachen Text mit dem useGT-Hook:

import { useGT } from 'gt-react';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('E-Mail-Adresse eingeben')}
      aria-label={t('E-Mail-Eingabefeld')}
    />
  );
}

Weitere Informationen findest du im Leitfaden zum Übersetzen von Strings.

Testen Ihrer App

Testen Sie Ihre Übersetzungen, indem Sie die Sprache wechseln:

1. Fügen Sie ein Dropdown zur Locale-Auswahl hinzu mit <LocaleSelector>:

   import { LocaleSelector } from 'gt-react';
   
   function App() {
     return <LocaleSelector />;
   }

2. Starten Sie Ihren Dev-Server:

   npmyarnbunpnpm

   npm run dev 

   yarn run dev 

   bun run dev 

   pnpm run dev 

3. Öffnen Sie localhost:3000 und wechseln Sie die Sprache über das Dropdown zur Locale-Auswahl.

Im Development-Modus werden Übersetzungen bei Bedarf geladen (kurze Ladezeit). Im Production-Betrieb ist alles vorab übersetzt.

Fehlerbehebung

Deployment

Für die Produktion musst du Inhalte vorab übersetzen, da die Übersetzung zur Laufzeit deaktiviert ist (außer für die Funktionen <Tx> und tx).

1. Produktions-API-Schlüssel abrufen unter dash.generaltranslation.com.

   Produktionsschlüssel beginnen mit gtx-api- (im Unterschied zu Dev-Schlüsseln, die mit gtx-dev- beginnen). Erfahre mehr über Unterschiede zwischen Umgebungen.

2. Zu deiner CI/CD-Umgebung hinzufügen:

   GT_PROJECT_ID=your-project-id
   GT_API_KEY=gtx-api-your-production-key

   Niemals Produktionsschlüssel mit dem öffentlichen Variablenpräfix deines Frameworks versehen (wie VITE_, REACT_APP_ usw.) – sie dürfen ausschließlich serverseitig verwendet werden.

3. Den translate-Befehl ausführen, um deine Inhalte zu übersetzen:

   npx gtx-cli translate

   Du kannst das Verhalten des translate-Befehls mit der Datei gt.config.json konfigurieren.

   Siehe den Referenzleitfaden zum CLI-Tool für weitere Informationen.

4. Dein Build-Skript aktualisieren, um vor dem Build zu übersetzen:

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

Nächste Schritte

• Leitfaden zur <T>-Komponente – Detaillierter Einblick in die <T>-Komponente und JSX-Übersetzung
• Leitfaden zur String-Übersetzung – Verwendung von useGT für die Übersetzung von Strings
• Variable Komponenten – Dynamische Inhalte mit <Var>, <Num> usw. verarbeiten