Bringen Sie Ihre React-App in wenigen Minuten zum Übersetzen von Inhalten.

Voraussetzungen: React, grundlegende JavaScript-Kenntnisse

Installation

Installieren Sie 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 zur Verfügung. Sie verwaltet den Locale-Zustand, 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 eine Datei gt.config.json:

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

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

Umgebungsvariablen

Füge Folgendes in deine Umgebungsdatei für Hot Reloading während der Entwicklung ein:

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"

Hole dir deine kostenlosen API-Schlüssel unter dash.generaltranslation.com oder führe 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>
  );
}

Lesen Sie den Leitfaden zur Verwendung der <T>-Komponente für weitere Informationen.

Einfache Zeichenketten mit useGT

Für Attribute, Labels und Klartext 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')}
    />
  );
}

Siehe den Leitfaden zum Übersetzen von Strings für weitere Informationen.

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 Entwicklungsmodus werden Übersetzungen bei Bedarf geladen (kurze Ladezeit). In der Produktion ist alles vorab übersetzt.

Fehlerbehebung

Deployment

Für die Produktionsumgebung müssen Sie Inhalte vorab übersetzen, da Übersetzungen zur Laufzeit deaktiviert sind (ausgenommen 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). Weitere Informationen zu Unterschieden zwischen Umgebungen.

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

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

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

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

   npx gtx-cli translate

   Das Verhalten des translate-Befehls können Sie in der Datei gt.config.json konfigurieren.

   Weitere Informationen finden Sie im Referenzleitfaden zum CLI-Tool.

4. Ihr 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 – Ausführlicher Einblick in die <T>-Komponente und die JSX-Übersetzung
• Leitfaden zur Zeichenkettenübersetzung – Nutzung von useGT für Zeichenkettenübersetzungen
• Variable Komponenten – Dynamische Inhalte mit <Var>, <Num> usw. verarbeiten