JSX übersetzen

Übersicht

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

Am Ende dieser Anleitung wissen Sie, wie Sie die <T> Komponente korrekt verwenden und was Sie vermeiden sollten.

Wir behandeln folgende Themen:

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

So verwenden Sie die <T> Komponente

Angenommen, Sie haben einige HTML-Inhalte, die Sie übersetzen möchten.

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

Alles, was Sie tun müssen, ist, den Inhalt in eine <T> Komponente zu hüllen.

import { T } from 'gt-next';

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

Abhängig von der aktuell vom Benutzer gewählten Sprache wird die entsprechende Übersetzung angezeigt. Weitere Informationen dazu, wie Sie Ihren Nutzern das Wechseln der Sprache ermöglichen, finden Sie unter Sprachen wechseln.

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 Kontext-Prop ist hilfreich, damit die KI die Absicht der Übersetzung besser versteht.

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.

Hier bedeutet dynamischer Inhalt jeglichen 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 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, ihn in Ihre CD-Pipeline oder als Teil Ihres Build-Skripts aufzunehmen.

{
  "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 im CLI Tool Referenzhandbuch.

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.

Übersetzen von dynamischen Inhalten

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.

Alternativ, wenn Ihr Inhalt wirklich dynamisch ist und bei Bedarf übersetzt werden muss, können Sie die <Tx>-Komponente verwenden.

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 Entwicklungsumgebung ü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 Components und Branching Components.
• Erfahren Sie mehr über das Übersetzen von Zeichenketten.