<T> Referenz

Überblick

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

• Die <T> Komponente
• Designmuster
• Produktionsüberlegungen
• Einige Beispiele
• Häufige Fallstricke

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-react 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 Standard-Lokalisierung 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 tangential mit der <T>-Komponente zusammenhängen, aber ebenso wichtig sind, wie String-Übersetzung, fortgeschrittene Inhaltsübersetzung und Datenschutzbedenken.

Ihre <T>-Komponenten in einen <GTProvider> einwickeln

<T> wird verwendet, um statischen Text und JSX-Strukturen zu übersetzen. <T> MUSS in einen <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-react"; 
import MyApp from "./MyApp";
 
export default function App() {
  return (
    <GTProvider>
      <MyApp />
    </GTProvider> 
  );
}

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, selbst wenn sich die Sprache ändert.

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

Es gibt viele Variablenkomponenten: <Var>, <Num>, <Currency> und <DateTime>. Einige davon formatieren den Inhalt automatisch basierend auf der Benutzerlokalisierung neu. Andere markieren den Inhalt einfach als "nicht übersetzen". Diese Komponenten müssen auch nicht unbedingt in eine <T>-Komponente eingebettet werden, 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.

import { T, Plural } from 'gt-react';
 
export default function Count({ num }) {
  return (
    <T>
      <Plural
        n={num} // <-- zu überprüfende Variable
        singular={<p>Es gibt ein Element.</p>}  
        plural={<p>Es gibt mehrere Elemente.</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.

Übersetzen von Strings

Wenn Sie nur einen String übersetzen möchten, können Sie useGT() verwenden. Es wird verwendet, um Strings zur Buildzeit zu übersetzen.

function Greeting() {
  const t = useGT();
  return <p>{t('Hallo, mein Freund!')}</p>; 
}

Für weitere Informationen können Sie sich auf unseren Leitfaden zur Übersetzung von Strings beziehen.

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 den CLI-Tool Referenzleitfaden.

Hinzufügen von IDs zu <T>-Komponenten

Ein praktischer Debugging-Trick ist das Hinzufügen einer id-Eigenschaft 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 bereitstellen zu müssen.

import { T } from 'gt-react';
 
export default function Greeting() {
  return (
    <T id="greeting">
      Hallo, Welt!
    </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.

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

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 den CLI-Tool Referenzleitfaden.

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.

Datenschutzbedenken

Mit einigen Ausnahmen werden alle Inhalte, die in einer <T> Komponente eingeschlossen sind, an die General Translation 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 General Translation APIs zur Übersetzung gesendet werden. Die Lokalisierung aller Inhalte, die in einer Variablen Komponente eingeschlossen sind, wird lokal gehandhabt.

Beispiele

Grundlegende Verwendung

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

import { T } from 'gt-react';
 
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 je nach bereitgestelltem Kontext in unterschiedliche Übersetzungen aufzulösen.

import { T } from 'gt-react';
 
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 für die Basissprache keine Änderung geben.

Verschachtelte Komponenten

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

import { T } from 'gt-react';
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 Inhalt innerhalb einer Komponente haben, der nicht direkt an <T> übergeben wird, dieser nicht übersetzt wird.

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 der <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.

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.

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.

Bedingter Inhalt

Ähnlich wie beim Rendern von variablen Inhalten muss bedingter Inhalt 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-react';
 
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 zu aktivieren, umwickeln Sie Ihre App mit einem <GTProvider>.
• <T> übersetzt Inhalte zur Buildzeit, nicht zur Laufzeit. Die Entwicklung wird aus Bequemlichkeit eine bedarfsgerechte Übersetzung durchführen, aber dies ist im Produktionsumfeld nicht der Fall.

Nächste Schritte

• Entdecken Sie den Artikel zu variablen Komponenten und den Leitfaden zu verzweigten Komponenten.
• Erfahren Sie mehr über das Übersetzen von Zeichenfolgen in Ihrer Anwendung.