Überblick
Überblick über das Next.js‑SDK von General Translation
Einführung
Das Next.js-SDK von General Translation ist eine Open-Source-Bibliothek für Internationalisierung (i18n) in Next.js-Anwendungen.
Es stellt einen umfassenden Satz an Tools bereit, um Ihre Next.js-Anwendung einfach und wartbar zu internationalisieren, mit Funktionsparität zu anderen gängigen i18n-Bibliotheken. Aufbauend auf dem React SDK bietet es zusätzliche, Next.js-spezifische Funktionen.
Das SDK kann eigenständig ohne die Plattform von General Translation verwendet werden und verhält sich ähnlich wie andere i18n-Bibliotheken.
Es lässt sich jedoch auch in unsere Plattform integrieren und bietet dann erweiterte Funktionen:
- Hot Reloading von Übersetzungen in der Entwicklung
- Automatische KI-Übersetzungen
- Synchronisierung von Übersetzungen mit der General Translation-Plattform
- Native Integration mit unserer Translation-CDN (Content Delivery Network)
- On-Demand-Übersetzung von React-Komponenten in der Produktion (serverseitig)
Konzepte
Es gibt 6 zentrale Konzepte, die du beim SDK kennen solltest.
Initialisierung mit withGTConfig
Die Komponente <GTProvider>
Die Komponente <T>
Der Hook useGT
Die Funktion msg für gemeinsame Strings
(Optional) Der Hook useTranslations
Initialisierung mit withGTConfig
Die Funktion withGTConfig initialisiert das SDK in Ihrer Next.js‑Anwendung.
Fügen Sie sie Ihrer Datei next.config.[js|ts] hinzu, um das SDK zu konfigurieren:
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Ihre next.config.ts options
};
export default withGTConfig(nextConfig, {
// Ihre GT-Konfiguration
});Weitere Informationen finden Sie in der API-Referenz zu withGTConfig.
Die <GTProvider>-Komponente
Die <GTProvider>-Komponente stellt Ihrer Anwendung einen Übersetzungskontext bereit, einschließlich der aktuellen Sprache und der zugehörigen Übersetzungen.
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}Wichtig: Der Provider sollte Ihre gesamte Anwendung umschließen und so weit oben wie möglich im Komponentenbaum platziert werden, z. B. in Ihrem Root-Layout.
Der Provider wird nur für clientseitige Funktionen benötigt. Reine serverseitige Anwendungen benötigen ihn nicht, er kann jedoch trotzdem eingebunden werden.
Weitere Informationen finden Sie in der API-Referenz zu GTProvider.
Die <T>-Komponente
Die <T>-Komponente ist die empfohlene Methode, um Inhalte in Ihrer Anwendung zu übersetzen.
Sie ist eine React-Komponente, die beliebige JSX-Elemente umschließen kann und den Inhalt des Elements automatisch in einer unterstützten Sprache rendert.
Beispiele
<T>
<div>Hallo, Welt!</div>
</T><T>
<div>
<h1> Hier ist ein Bild </h1>
<img src="https://example.com/image.png" alt="Beispiel" />
</div>
</T><T>
Formatierungen lassen sich mit der Komponente `<T>` ganz einfach vornehmen.
<Num>{1000}</Num>
<DateTime>{new Date()}</DateTime>
<Currency currency="USD">{1000}</Currency>
</T>Die <T>-Komponente arbeitet mit Variablenkomponenten wie <Num>, <DateTime> und <Currency> zusammen, um Inhalte dynamisch zu formatieren.
Siehe den Leitfaden zur Komponente [<T>], um die verschiedenen Einsatzmöglichkeiten der <T>-Komponente kennenzulernen.
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, mit der sich Strings übersetzen lassen.
const t = useGT();
t('Hallo, Welt!');Im Vergleich zur <T>-Komponente bietet der useGT-Hook mehr Flexibilität in Ihrer Codebasis.
Wenn Sie beispielsweise eine komplexe Datenstruktur mit verschachtelten Strings haben, ist eine <T>-Komponente schwieriger zu verwenden.
const t = useGT();
const data = {
title: t('Hallo, Welt!'),
description: t('Dies ist eine Beschreibung.'),
};Siehe den Leitfaden zu Strings, um mehr über den Hook useGT zu erfahren.
Die Funktion msg
Die Funktion msg dient dazu, Texte zur Übersetzung zu markieren, die in mehreren Komponenten verwendet oder in Konfigurationsobjekten gespeichert werden.
Das ist besonders nützlich für gemeinsam genutzte Inhalte wie Navigationslabels, Formularmeldungen oder beliebigen Text, der an mehreren Stellen in Ihrer Anwendung erscheint.
// Zeichenketten für die Übersetzung markieren
import { msg } from 'gt-next';
const navItems = [
{ label: msg('Startseite'), href: '/' },
{ label: msg('Über uns'), href: '/about' },
{ label: msg('Kontakt'), href: '/contact' }
];// Decode and use the marked strings
import { useMessages } from 'gt-next';
function Navigation() {
const m = useMessages();
return (
<nav>
{navItems.map(item => (
<a key={item.href} href={item.href}>
{m(item.label)}
</a>
))}
</nav>
);
}Die Funktion msg codiert Strings mit Übersetzungsmetadaten, und useMessages (oder getMessages für Serverkomponenten) decodiert sie.
Weitere Informationen zur Funktion msg finden Sie im Leitfaden Shared Strings.
Der Hook useTranslations
Der Hook useTranslations ist ein React-Hook, der eine Funktion zurückgibt, mit der Übersetzungen für einen bestimmten Schlüssel abgerufen werden können.
const dictionary = {
hello: {
world: 'Hallo, Welt!',
},
};const translate = useTranslations();
translate('hello.world');Dieses Verhalten ähnelt anderen Übersetzungsbibliotheken wie react-i18next und next-intl.
Wir raten davon ab, den Hook useTranslations in Ihrer Anwendung zu verwenden. Häufiger Einsatz des Hooks useTranslations erschwert die Wartung Ihrer Codebasis
und führt zu hoher technischer Schuldenlast.
Stattdessen empfehlen wir die Verwendung der Komponente <T> oder des Hooks useGT.
Wenn Sie von einer anderen i18n‑Bibliothek migrieren, ist der Hook useTranslations ein Drop‑in‑Ersatz und kann für die schrittweise Migration Ihrer Codebasis hilfreich sein.
Weitere Informationen zum Hook useTranslations finden Sie im Leitfaden zu dictionaries.
Siehe die useTranslations API Reference für weitere Details.
Nächste Schritte
- Erfahren Sie, wie Sie Ihr Next.js‑Projekt mit dem SDK einrichten: Schnellstart
- Erfahren Sie, wie Sie JSX‑Inhalte mit der Komponente
<T>übersetzen: JSX‑Übersetzungsleitfaden - Erfahren Sie, wie Sie Zeichenketten mit dem Hook
useGTübersetzen: Leitfaden zur Zeichenkettenübersetzung - Erfahren Sie mehr über gemeinsam genutzte Zeichenketten mit der Funktion
msg: Leitfaden zu gemeinsamen Zeichenketten
Wie ist diese Anleitung?