JSX übersetzen

Übersicht

Diese Anleitung führt Sie durch die Verwendung der <T> Komponente, um JSX-Inhalte zu internationalisieren.

Am Ende dieser Anleitung kennen Sie die korrekte Syntax für die Verwendung der <T> Komponente und wissen, was zu vermeiden ist.

Wir behandeln folgende Themen:

Wenn Sie wissen möchten, wie Variable Components oder Branching Components verwendet werden, lesen Sie bitte die jeweiligen Anleitungen.

So verwendest du die <T> Komponente

Angenommen, du hast einige HTML-Inhalte, die du übersetzen möchtest.

function Greeting() {
  return <p>Hello, world!</p>;
}

Alles, was du tun musst, ist, den Inhalt in eine <T> Komponente zu hüllen.

import { T } from 'gt-react';

function Greeting() {
  return <T><p>Hello, world!</p></T>;
}

Je nach aktuell ausgewählter Sprache deines Nutzers wird die entsprechende Übersetzung angezeigt. Siehe Sprachen wechseln für weitere Informationen darüber, wie du deinen Nutzern das Wechseln der Sprache ermöglichst.

Zusätzliche Optionen

Kontext

In einigen Fällen möchten Sie möglicherweise zusätzlichen Kontext für die Übersetzung bereitstellen. Dies kann erreicht werden, indem Sie ein context-Prop an die <T>-Komponente übergeben.

<T context="toast, as in a pop-up notification">
  Click on the toast to dismiss it.
</T>

Dies ist nützlich in Fällen, in denen Wörter je nach Kontext mehrere Bedeutungen haben können. Zum Beispiel kann "toast" sich auf das Lebensmittel oder auf eine Pop-up-Benachrichtigung beziehen.

Das context-Prop hilft der KI, die Absicht der Übersetzung besser zu verstehen.

id

Sie können der <T>-Komponente auch ein id-Prop übergeben. Dies ist für Debugging-Zwecke nützlich und erleichtert die Bearbeitung der Übersetzung.

<T id="toast">
  Click on the toast to dismiss it.
</T>

Wann sollte die <T> Komponente verwendet werden

Obwohl die <T> Komponente sehr flexibel ist, ist sie nicht immer die beste Lösung.

Du solltest die <T> Komponente immer dann verwenden, wenn du statischen HTML- oder JSX-Inhalt hast.

Wann die <T> Komponente nicht verwendet werden sollte

VERWENDE die <T> Komponente NICHT, wenn du unsicheren dynamischen Inhalt hast.

Dynamischer Inhalt bedeutet hier jeglicher Inhalt, der sich zur Laufzeit ändern kann. Diese Regel gilt nicht, wenn du Variable Components oder Branching Components verwendest.

Die folgenden Beispiele zeigen eine ungültige Verwendung der <T> Komponente:

<T>
  <p>Your username is {username}</p>
</T>

<T>
  <p>Current date: {new Date().toLocaleDateString()}</p>
</T>

<T>
  <p>Logical Expressions: {username === 'admin' ? 'Yes' : 'No'}</p>
</T>

<T>
  <p>Conditional Rendering: {isAdmin ? 'Yes' : 'No'}</p>
</T>

const chatMessage = getChatMessageFromServer();
<T>
  <p>{chatMessage}</p>
</T>

Beispiele

Hier sind einige Beispiele, wie man die <T> Komponente verwendet. Alle diese Beispiele sind korrekt.

1. HTML-Inhalt

<T>
  <p>Hello, world!</p>
</T>

<p>Hello, world!</p>

2. Einfacher JSX-Inhalt

<T>
  <Button>Click me!</Button>
</T>

<Button>Click me!</Button>

3. Komplexer JSX-Inhalt

<T>
  <Tooltip>
    <TooltipTrigger>
      <div className="flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground">
        <AlertCircle className="h-4 w-4" />
        <span>Free Usage</span>
      </div>
    </TooltipTrigger>
    <TooltipContent>
      <p>
        You are nearing your free monthly limit. Please
        upgrade your plan to avoid any disruptions to your
        service.
      </p>
    </TooltipContent>
  </Tooltip>
</T>

<Tooltip>
  <TooltipTrigger>
    <div className="flex items-center gap-2 rounded-full bg-destructive px-3 py-1.5 text-sm text-destructive-foreground">
      <AlertCircle className="h-4 w-4" />
      <span>Free Usage</span>
    </div>
  </TooltipTrigger>
  <TooltipContent>
    <p>
      You are nearing your free monthly limit. Please
      upgrade your plan to avoid any disruptions to your
      service.
    </p>
  </TooltipContent>
</Tooltip>

Produktionsüberlegungen

Deployment in die Produktion

Stellen Sie sicher, dass Sie den translate-Befehl ausführen, bevor Sie in die Produktion deployen, damit alle Übersetzungen zur Laufzeit verfügbar sind. Wir empfehlen, diesen Befehl in Ihre CD-Pipeline oder als Teil Ihres Build-Skripts einzubinden.

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

Eine ausführlichere Anleitung zum Deployment Ihrer Anwendung finden Sie im Deployment Tutorial. Weitere Informationen zum Befehl finden Sie in der CLI Tool Referenz.

Verhalten: Entwicklung vs. Produktion

In der Entwicklung übersetzt die <T> Komponente Inhalte bei Bedarf. Das bedeutet, dass beim Rendern der Komponente eine sofortige Übersetzung erfolgt. Die Bibliothek macht dies aus Gründen der Bequemlichkeit, um die Entwicklung mit anderen Sprachen zu erleichtern.

Um dieses Verhalten zu aktivieren, fügen Sie einfach einen Dev API-Schlüssel zu Ihrer Umgebung hinzu.

In der Produktion werden alle Übersetzungen, die die <T> Komponente verwendet, zur Build-Zeit abgeschlossen. Das bedeutet, dass Sie den Übersetzungsbefehl ausführen müssen, bevor Sie Ihre Anwendung deployen.

Datenschutzbedenken

Mit einigen Ausnahmen wird sämtlicher Inhalt, der in eine <T> Komponente eingebettet ist, an die General Translation API zur Übersetzung gesendet. Dies ist möglicherweise nicht wünschenswert, wenn sensible Daten wie Benutzernamen, Kontonummern usw. gerendert werden sollen.

Um dieses Problem zu umgehen, verwenden Sie Variable Components, um private Informationen zu verarbeiten. So wird sichergestellt, dass keine sensiblen Daten an die General Translation API zur Übersetzung gesendet werden. Die Lokalisierung aller Inhalte, die in eine Variable Component eingebettet sind, erfolgt lokal.

Häufige Fallstricke

Nur direkte Nachkommen

Die <T>-Komponente übersetzt nur den Text, der direkt als Kind übergeben wird. Das bedeutet, dass Inhalte innerhalb einer Komponente, die nicht direkt an <T> übergeben werden, nicht übersetzt werden.

Lassen Sie uns dies mit einem Beispiel veranschaulichen:

function UntranslatedContent() {
  return (
    <p>This content is not translated</p>
  );
}

export default function DisplayGreetings() {
  return (
    <T>
      <h1>Hello, this text will be translated</h1>
      <UntranslatedContent />
    </T>
  );
}

In diesem Beispiel wird der Inhalt innerhalb von <UntranslatedContent> nicht übersetzt. Nur der Inhalt, der sich direkt innerhalb von <T> befindet, wird übersetzt, wie das <h1>-Tag und dessen Kinder.

Was ist die Lösung?

Wickeln Sie den Text direkt in die <T>-Komponente, wie folgt:

function TranslatedContent() {
  return (
    <T>
      <p>This content <b>IS</b> translated</p>
    </T>
  );
}

export default function DisplayGreetings() {
  return (
    <>
      <T>
        <h1>Hello, this text will be translated</h1>
      </T>
      <TranslatedContent />
    </>
  );
}

Verschachtelte <T>-Komponenten

Das Verschachteln von <T>-Komponenten ist nicht erlaubt. Aufgrund des Renderingsystems von React kann dies zu unerwartetem Verhalten und Performance-Problemen führen.

Hier ist ein Beispiel, wie man es nicht machen sollte:

function SomeComponent() {
  return (
    <T>
      Hello, friend!
    </T>
  );
}

export default function NestedTranslation() {
  return (
    <T>
      <T> {/* Don't do this! */} 
        Hello, world! 
      </T>
      <SomeComponent /> {/* This still counts. Don't do this! */}
    </T>
  );
}

Die Lösung besteht darin, die äußerste <T>-Komponente zu entfernen.

Dynamische Inhalte übersetzen

Wenn Sie versuchen, dynamische Inhalte mit der <T>-Komponente zu umschließen, wird das CLI-Tool einen Fehler ausgeben.

Zum Beispiel führt Folgendes zu einem Fehler:

const username = 'John Doe';
<T>
  <p>Your username is {username}</p>
</T>

Um dies zu umgehen, versuchen Sie, Variable Components oder Branching Components zu verwenden, um den dynamischen Inhalt zu umschließen.

Zusammenfassung

• <T>-Komponenten werden verwendet, um beliebigen JSX-Inhalt zu internationalisieren.
• <T>-Komponenten sollten nicht für dynamische Inhalte verwendet werden, ohne Variable-Komponenten oder Verzweigungskomponenten zu nutzen.
• In der Entwicklung übersetzt die <T>-Komponente Inhalte bei Bedarf.
• In der Produktion werden alle Übersetzungen, die die <T>-Komponente verwendet, zur Build-Zeit abgeschlossen.

Nächste Schritte

• Lesen Sie mehr über die API für die <T> Komponente.
• Entdecken Sie Variable Komponenten und Verzweigungskomponenten.
• Erfahren Sie mehr über das Übersetzen von Zeichenketten.