Überblick

Einführung

Das General Translation Next.js SDK ist eine Open-Source-Internationalisierungsbibliothek (i18n) für Next.js.

Es bietet eine Reihe von Tools, die Ihnen helfen, Ihre Next.js-Anwendung auf einfache und wartbare Weise zu internationalisieren, mit Funktionsparität zu anderen beliebten i18n-Bibliotheken. Es basiert auf dem React SDK und bietet zusätzliche Funktionen, die spezifisch für Next.js sind.

Das Next.js SDK kann ohne die General Translation-Plattform verwendet werden und verhält sich sehr ähnlich wie andere i18n-Bibliotheken.

Es integriert sich jedoch auch mit unserer Plattform und bietet zusätzliche Funktionen wie:

Translation Hot Reloading in der Entwicklung
Automatische KI-Übersetzungen
Synchronisierung von Übersetzungen mit der General Translation-Plattform
Native Integration mit unserem Übersetzungs-CDN
On-Demand-Übersetzung von React-Komponenten in der Produktion (serverseitig)

Konzepte

Es gibt 5 Hauptkonzepte, die Sie über das SDK verstehen sollten.

Initialisierung mit withGTConfig

Die <GTProvider> Komponente

Die <T> Komponente

Der useGT Hook

(Optional) Der useTranslations Hook

Initialisierung mit `withGTConfig`

Die withGTConfig Funktion ist eine Funktion, die zur Initialisierung des SDK in einer Next.js Anwendung verwendet wird.

Sie sollte in Ihrer next.config.[js|ts] Datei platziert werden und wird zur Konfiguration des SDK verwendet.

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Your next.config.ts options
};

export default withGTConfig(nextConfig, {
  // Your GT configuration
});

Siehe die withGTConfig API Referenz für weitere Informationen.

Die `<GTProvider>` Komponente

import { GTProvider } from 'gt-next';

Die <GTProvider> Komponente ist die Hauptkomponente, die Sie zu Ihrer Anwendung hinzufügen müssen.

Sie wird verwendet, um dem Rest Ihrer Anwendung Kontext bereitzustellen.

Dieser Kontext umfasst die aktuelle Sprache und die relevanten Übersetzungen für diese Sprache.

Der Provider ist nur erforderlich, wenn Sie clientseitige Features verwenden. Wenn Sie nur serverseitige Features verwenden, ist der Provider nicht erforderlich, kann aber dennoch eingebunden werden.

Wichtige Überlegungen

Der Provider sollte Ihre gesamte Anwendung umschließen.
Idealerweise sollte er so hoch wie möglich im Baum platziert werden, beispielsweise in Ihrem Root-Layout.

Siehe die GTProvider Seite für weitere Informationen.

Die `<T>` Komponente

Die <T> Komponente ist der empfohlene Weg, um Inhalte in Ihrer Anwendung zu übersetzen.

Es ist eine React-Komponente, die verwendet werden kann, um jedes JSX-Element zu umhüllen und automatisch den Inhalt des Elements in eine unterstützte Sprache zu rendern.

Wir empfehlen die Verwendung der <T> Komponente wo immer möglich, da sie die größte Flexibilität bei Übersetzungen bietet.

Im Gegensatz zu Strings kann die <T> Komponente verwendet werden, um HTML-Inhalte zu übersetzen, was sie viel mächtiger macht als String-Übersetzungen.

Beispiele

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

<T>
  <div>
    <h1> Here is an image </h1>
    <img src="https://example.com/image.png" alt="Example" />
  </div>
</T>

<T>
  Formatting can be done easily with the `<T>` component.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency>{1000}</Currency>
</T>

Siehe den components Leitfaden, um mehr über die verschiedenen Verwendungsmöglichkeiten der <T> Komponente zu erfahren.

Siehe die T API Reference für die API der <T> Komponente.

Der `useGT` Hook

Der useGT Hook ist ein React Hook, der ähnlich wie die <T> Komponente verwendet werden kann, mit einigen Kompromissen.

Der Hook gibt eine Funktion zurück, die zum Übersetzen von Strings verwendet werden kann.

const translate = useGT();

translate('Hello, world!');

Im Vergleich zur <T> Komponente ermöglicht der useGT Hook mehr Flexibilität in Ihrer Codebasis.

Wenn Sie beispielsweise eine komplexe Datenstruktur mit verschachtelten Strings haben, wäre eine <T> Komponente schwieriger zu verwenden.

const t = useGT();
const data = {
  title: t('Hello, world!'),
  description: t('This is a description'),
};

Siehe den strings Leitfaden, um mehr über den useGT Hook zu erfahren.

Siehe die useGT API Referenz für weitere Informationen.

Der `useTranslations` Hook

Der useTranslations Hook ist ein React Hook, der eine Funktion zurückgibt, die verwendet werden kann, um Übersetzungen für einen gegebenen Schlüssel abzurufen.

dictionary.ts

const dictionary = {
  hello: {
    world: 'Hello, world!',
  },
};

App.tsx

const translate = useTranslations();
translate('hello.world');

Dieses Verhalten ist ähnlich zu anderen Übersetzungsbibliotheken, wie react-i18next und next-intl.

Wir empfehlen nicht, den useTranslations Hook in Ihrer Anwendung zu verwenden. Häufige Verwendung des useTranslations Hooks wird Ihre Codebasis schwieriger zu warten machen und zu großen technischen Schulden führen.

Stattdessen empfehlen wir die Verwendung der <T> Komponente oder des useGT Hooks.

Wenn Sie von einer anderen i18n-Bibliothek migrieren, ist der useTranslations Hook ein direkter Ersatz und kann nützlich für die schrittweise Migration Ihrer Codebasis sein.

Siehe den dictionaries Leitfaden, um mehr über den useTranslations Hook zu erfahren.

Siehe die useTranslations API-Referenz für weitere Informationen.

Nächste Schritte

Erfahren Sie, wie Sie Ihr Next.js-Projekt mit dem SDK einrichten: Schnellstart
Erfahren Sie, wie Sie Strings mit dem useGT Hook übersetzen: Strings übersetzen
Erfahren Sie, wie Sie JSX-Inhalte mit der <T> Komponente übersetzen: JSX übersetzen

Überblick

Auf dieser Seite