General Translation  
DashboardBlogDiscord

<T> Referenz

Dies ist ein detaillierter Einblick in die <T> Komponente und die gt-next Bibliothek.

Überblick

Dieser Artikel bietet einen tiefen Einblick in die Verwendung der <T> Komponente in der gt-next Bibliothek. Bitte zögern Sie nicht, diese Seite nach Bedarf zu überspringen. Wir werden die folgenden Themen behandeln:

Wenn Sie nach Informationen zur Verwendung von Variablen Komponenten oder Verzweigungskomponenten suchen, lesen Sie bitte die jeweiligen Artikel.

Was ist die <T> Komponente?

Die <T> Komponente ist der primäre Weg, um Text und Inhalte in der gt-next Bibliothek zu übersetzen. Sie ermöglicht die Inline-Übersetzung von Text und JSX-Strukturen und bietet eine direktere Möglichkeit, Übersetzungen in Ihrer Anwendung zu verwalten. Dies ist oft bequemer für den Entwickler, da es eine direktere Kontrolle über den Übersetzungsinhalt ermöglicht.

Die <T> Komponente unterstützt statischen Text, JSX-Strukturen und kontextbezogene Übersetzungen. Wenn keine Übersetzung verfügbar ist, wird der Inhalt elegant in der Standardsprache der Anwendung angezeigt.

<T>
  <p>Hallo, Welt!</p>
</T>

Designmuster

In diesem Abschnitt werden wir gängige Designmuster erläutern, die mit der <T>-Komponente verwendet werden. Dies wird auch Themen berühren, die nur am Rande mit der <T>-Komponente zu tun haben, aber ebenso wichtig sind, wie String-Übersetzung, fortgeschrittene Inhaltsübersetzung und Datenschutzbedenken.

Ihre <T>-Komponenten in einem <GTProvider> einbetten

<T> wird verwendet, um statischen Text und JSX-Strukturen zu übersetzen. Für clientseitige Komponenten MUSS <T> in einem <GTProvider> auf einer höheren Ebene eingebettet werden. Unser Rat ist, Ihre Anwendung auf der Root-Ebene in einen <GTProvider> einzubetten, um diesen Kontext bereitzustellen.

import { GTProvider } from 'gt-next';
import { getLocale } from "gt-next/server";
 
export default async function RootLayout({ children }) {
  const locale = await getLocale();
  return (
    <html lang={locale}>
      <body>
        <GTProvider>{children}</GTProvider> // [!code highlight]
      </body>
    </html>
  );
}

Ausnahmen: Serverseitige <T>-Komponenten

Für serverseitiges Rendering ist der <GTProvider> für <T>-Komponenten optional.

import { GTProvider } from 'gt-next';
import { getLocale } from "gt-next/server";
 
export default function RootLayout({ children }) {
  const locale = await getLocale();
  return (
    <html lang={locale}>
      <body>
        <T> Hello, world! </T>  // [!code highlight]
        
        <GTProvider>{children}</GTProvider> // [!code highlight]
      </body>
    </html>
  );
}

Variablen in <T>-Komponenten

Variablenkomponenten können in <T>-Komponenten verwendet werden, um (1) dynamische Werte anzuzeigen und/oder (2) Inhalte zu markieren, die nicht übersetzt werden sollen. Denken Sie an Dinge wie den Namen eines Benutzers: er ist (1) von Person zu Person unterschiedlich und (2) sollte sich nicht ändern, auch wenn sich die Sprache ändert.

DynamicGreeting.js
import { T, Var } from 'gt-next';
 
export default function DynamicGreeting({ user }) {
  return (
    <T>
      Hello, <Var>{user.name}</Var>! // [!code highlight]
    </T>
  );
}

Es gibt viele Variablenkomponenten: <Var>, <Num>, <Currency> und <DateTime>. Einige davon werden den Inhalt automatisch basierend auf der Benutzersprache neu formatieren. Andere werden den Inhalt einfach als "nicht übersetzen" markieren. Außerdem müssen diese Komponenten nicht unbedingt in einer <T>-Komponente eingebettet sein, um den Inhalt neu zu formatieren.

Lesen Sie mehr darüber in diesem Artikel über Variablenkomponenten.

Verzweigungen in <T>-Komponenten

Verzweigungskomponenten können verwendet werden, um basierend auf Bedingungen unterschiedliche Inhalte für Übersetzungen anzuzeigen. Dazu gehören <Plural> und <Branch> Komponenten. Wir verwenden diese Komponenten, weil sie einen optimierten Übersetzungsprozess ermöglichen.

Zum Beispiel ermöglicht die <Plural>-Komponente, Sätze zu markieren, die bei der Übersetzung pluralisiert werden sollen.

Count.js
import { T, Plural } from 'gt-next';
 
export default function Count({ num }) {
  return (
    <T>
      <Plural
        n={num} // <-- zu überprüfende Variable
        singular={<p>There is one item.</p>}  
        plural={<p>There are multiple items.</p>}  
      />
    </T>
  );
}

Es ist auch nützlich, da es Ihre Pluralisierungslogik in Ihrer Anwendung in Ihrer Basissprache standardisiert.

Sie können je nach verwendeter Komponente unterschiedliche Optionen angeben. Lesen Sie mehr darüber im Artikel Verzweigungskomponenten.

Strings übersetzen

Wenn Sie nur einen String übersetzen möchten, können Sie useGT(), getGT() oder tx() verwenden.

useGT() und getGT() werden verwendet, um Strings zur Buildzeit zu übersetzen.

Greeting.js
function Greeting() {
  const t = useGT();  // client side
  const t = await getGT(); // server side
  return <p>{t('Hello, my friend!')}</p>; 
}

tx() wird verwendet, um Zeichenfolgen zur Laufzeit zu übersetzen.

FavoriteFlavor.js
function async FavoriteFlavor({ flavor }) {
  return <p>{await tx(`Your favorite ice cream flavor is ${flavor}`)}</p>; 
}

Für weitere Informationen können Sie unseren Leitfaden zur Übersetzung von Zeichenfolgen konsultieren.

Hinzufügen von IDs zu <T> Komponenten

Ein praktischer Debugging-Trick ist das Hinzufügen eines id-Props zu Ihren <T> Komponenten. Dies ermöglicht es Ihnen, nachzuverfolgen, welche Übersetzungen in Ihrer Anwendung verwendet werden. Es ermöglicht Ihnen auch, den Übersetzungseditor zu verwenden, um Änderungen an Ihren Übersetzungen vorzunehmen, ohne neu zu deployen.

Greeting.js
import { T } from 'gt-next';
 
export default function Greeting() {
  return (
    <T id="greeting">
      Hello, world!
    </T>
  );
}

Produktionsüberlegungen

Bereitstellung in der Produktion

Stellen Sie sicher, dass Sie den Übersetzungsbefehl ausführen, bevor Sie in die Produktion bereitstellen, damit alle Übersetzungen zur Laufzeit verfügbar sind. Wir empfehlen, ihn in Ihre CD-Pipeline oder als Teil Ihres Build-Skripts aufzunehmen.

package.json
{
  "scripts": {
    "build": "npx gtx-cli translate --languages fr es ja && next build",
  }
}

Das war's! Sie haben Ihre Anwendung erfolgreich ins Französische, Spanische und Japanische übersetzt.

Für eine detailliertere Anleitung zur Bereitstellung Ihrer Anwendung lesen Sie bitte den Bereitstellungsleitfaden. Für weitere Informationen zum Befehl lesen Sie bitte die CLI-Tool Referenzanleitung.

Verhalten: Entwicklung vs Produktion

In der Entwicklung wird die <T> Komponente Inhalte bei Bedarf übersetzen. Das bedeutet, dass die Komponente bei der Darstellung sofort eine Übersetzung durchführt. Wir tun dies aus 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 wird die <T> Komponente Inhalte zur Build-Zeit übersetzen. Das bedeutet, dass Sie den Übersetzungsbefehl ausführen müssen, bevor Sie Ihre Anwendung bereitstellen.

Tipp: Wenn Sie das Produktionsverhalten in der Entwicklung simulieren möchten, verwenden Sie einfach einen Produktions-API-Schlüssel in Ihrem Entwicklungs-Build.

Datenschutzbedenken

Mit einigen Ausnahmen werden alle Inhalte, die in einer <T> Komponente eingeschlossen sind, an die allgemeinen Übersetzungs-APIs zur Übersetzung gesendet. Dies ist möglicherweise nicht wünschenswert für die Darstellung sensibler Daten wie Benutzernamen, Kontonummern usw.

Um dieses Problem zu umgehen, verwenden Sie Variable Komponenten, um private Informationen zu verarbeiten. Dies stellt sicher, dass keine sensiblen Daten an die allgemeinen Übersetzungs-APIs zur Übersetzung gesendet werden. Die Lokalisierung aller Inhalte, die in einer beliebigen Variablenkomponente eingeschlossen sind, wird lokal gehandhabt.

Beispiele

Grundlegende Verwendung

Der einfachste Anwendungsfall für <T> ist die Übersetzung von statischem Text.

import { T } from 'gt-next';
 
export default function BasicUsage() {
  return (
    <T>
      Hello, world!
    </T>
  );
}

Dieses Beispiel stellt sicher, dass "Hello, world!" basierend auf der Spracheinstellung des Benutzers übersetzt wird. Zum Beispiel könnte es in einer spanischen Spracheinstellung als "¡Hola, mundo!" angezeigt werden.

Kontext

Die <T> Komponente unterstützt zusätzlichen Kontext, um Übersetzungen zu verfeinern. Das Hinzufügen einer Kontext-Eigenschaft ermöglicht es, dasselbe id zu unterschiedlichen Übersetzungen je nach bereitgestelltem Kontext aufzulösen.

import { T } from 'gt-next';
 
export default function FormalGreeting() {
  return (
    <T context="formal">
      Hi there!
    </T>
  );
}

Zum Beispiel könnte der Kontext "formal" eine Übersetzung wie "Guten Tag, alle zusammen!" ergeben, während dasselbe id ohne Kontext in der anderen Sprache "Hi there!" ergeben könnte. Natürlich würde es keine Änderung für die Basissprache geben.

Verschachtelte Komponenten

Die <T> Komponente kann auch JSX-Strukturen übersetzen. Alle Kinder der <T> werden übersetzt.

import { T } from 'gt-next';
import CustomButton from './CustomButton';
 
export default function Page() {
  return (
    <T>
      This will be translated
      <div>
        <div>
          <div>
            <div>
              <CustomButton>This text will also be translated!</CustomButton>
            </div>
          </div>
        </div>
      </div>
    </T>
  );
}

Häufige Fallstricke

Nur direkte Nachkommen

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

Lassen Sie uns dies mit einem Beispiel veranschaulichen:

function UntranslatedContent() {
  return (
    <p>Dieser Inhalt wird nicht übersetzt</p>
  );
}
 
export default function DisplayGreetings() {
  return (
    <T>
      <h1>Hallo, dieser Text wird übersetzt</h1>
      <UntranslatedContent />
    </T>
  );
}

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

Dies geschieht aufgrund der Art und Weise, wie React Komponenten rendert. Es ist ein wenig kompliziert, aber im Wesentlichen weiß React nicht, was der Inhalt einer Komponente ist, bis sie gerendert wurde. Daher werden die Inhalte von Komponenten wie <UntranslatedContent> nicht übersetzt. Jedoch wird jeder Text, der direkt zwischen den beiden <T> Tags steht, übersetzt.

Hinweis: Eine gute Faustregel ist, dass jeder Inhalt, der buchstäblich zwischen den beiden <T> im Datei steht, übersetzt wird. Sie können immer ein weiteres <T> hinzufügen, um den Inhalt zu übersetzen, der nicht übersetzt wird, obwohl das Verschachteln von <T> Komponenten nicht empfohlen wird.

Was ist die Lösung?

Ihr erster Instinkt könnte sein, eine zusätzliche <T> Komponente innerhalb von <UntranslatedContent> hinzuzufügen, aber das wird nicht empfohlen. Wir besprechen dies weiter unten.

Die Lösung besteht darin, den Text immer direkt in der <T> Komponente zu umschließen, wie folgt:

function TranslatedContent() {
  return (
    <T>
      <p>Dieser Inhalt <b>WIRD</b> übersetzt</p>
    </T>
  );
}
 
export default function DisplayGreetings() {
  return (
    <>
      <T>
        <h1>Hallo, dieser Text wird übersetzt</h1>
      </T>
      <TranslatedContent />
    </>
  );
}

Was ist mit Variablen?

Variablen sind etwas komplizierter, da sie dazu neigen, ihre Werte zu ändern. Wir empfehlen die Verwendung von Variable Components zur Anzeige dynamischer Werte und Branching Components für bedingte Logik.

Wenn Sie dynamische Inhalte zur Laufzeit übersetzen möchten, schauen Sie sich tx() und <Tx> an.

Verschachtelte <T> Komponenten

Das Verschachteln von <T> Komponenten ist nicht erlaubt. Aufgrund des Rendering-Systems von React kann dies zu unerwartetem Verhalten und Leistungsproblemen führen, wenn auf Abruf übersetzt wird.

Hier ist ein Beispiel für was man nicht tun sollte:

function SomeComponent() {
  return (
    <T>
      Hallo, Freund!
    </T>
  );
}
 
export default function NestedTranslation() {
  return (
    <T>
      <T> {/* Mach das nicht! */} // [!code highlight]
        Hallo, Welt!
      </T>
      <SomeComponent /> {/* Das zählt immer noch. Mach das nicht! */} // [!code highlight]
    </T>
  );
}

Die Lösung hier ist, die äußerste <T> Komponente zu entfernen.

Bedingte Inhalte

Ähnlich wie bei der Darstellung variabler Inhalte müssen bedingte Inhalte innerhalb einer <T> Komponente ordnungsgemäß behandelt werden. Es ist immer am besten, den bedingten Inhalt in einer Branching Component zu umschließen, um die Übersetzung des Inhalts zu optimieren.

import { T, Branch } from 'gt-next';
 
export default function Header({ user }) {
  return (
    <T>
      <h2>
        <Branch
          branch={user.hasAccount}
          true={<p>Willkommen zurück, {user.name}!</p>}
          false={<p>Bitte loggen Sie sich ein, um fortzufahren.</p>}
        />
      </h2>
    </T>
  );
}

Notizen

  • <T>-Komponenten werden verwendet, um beliebige JSX-Inhalte zu übersetzen.
  • Um Übersetzungen in Client-Komponenten zu aktivieren, umwickeln Sie Ihre App mit einem <GTProvider>.
  • <T> übersetzt Inhalte zur Build-Zeit, nicht zur Laufzeit. Die Entwicklung wird zur Bequemlichkeit eine bedarfsgerechte Übersetzung durchführen, aber dies ist im Produktionsbetrieb nicht der Fall.

Nächste Schritte

Auf GitHub bearbeiten

Next.js Schnellstart

Internationalisieren Sie Ihre Next.js-App in 5 Minuten mit gt-next

Wörterbücher Referenz

Ein Überblick über das Wörterbuchmuster

Auf dieser Seite