Überblick
Überblick über das Next.js‑SDK von General Translation
Einführung
Das General Translation Next.js SDK ist eine Open-Source-Bibliothek für Internationalisierung (i18n) in Next.js-Anwendungen.
Es stellt einen umfassenden Werkzeugkasten 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 auch eigenständig, ohne die General Translation Plattform, 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 unserem Translation-CDN
- On-Demand-Übersetzung von React-Komponenten in der Produktion (serverseitig)
Konzepte
Es gibt 6 zentrale Konzepte, die man beim SDK verstehen sollte.
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-Optionen
};
export default withGTConfig(nextConfig, {
// Ihre GT-Konfiguration
});Siehe die API-Referenz zu withGTConfig für weitere Informationen.
Die <GTProvider>-Komponente
Die <GTProvider>-Komponente stellt Ihrer Anwendung den Übersetzungskontext bereit, einschließlich der aktuellen Sprache und der entsprechenden Ü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, zum Beispiel in Ihrem Root-Layout.
Der Provider wird nur für clientseitige Features benötigt. Reine serverseitige Anwendungen benötigen ihn nicht, er kann aber dennoch eingebunden werden.
Weitere Informationen finden Sie in der API-Referenz zu GTProvider.
Die <T>-Komponente
Die Komponente <T> ist die empfohlene Methode, Inhalte in Ihrer Anwendung zu übersetzen.
Sie ist eine React‑Komponente, die beliebige JSX‑Elemente umschließen kann und deren Inhalt 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>
Die Formatierung lässt sich einfach mit der `<T>`-Komponente durchführen.
<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 dynamische Inhalte 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, allerdings mit einigen Abwägungen.
Der Hook gibt eine Funktion zurück, mit der sich Strings übersetzen lassen.
const t = useGT();
t('Hallo, Welt!');Im Vergleich zur Komponente <T> bietet der Hook useGT mehr Flexibilität in Ihrer Codebasis.
Wenn Sie beispielsweise eine komplexe Datenstruktur mit verschachtelten Zeichenketten haben, wäre die Verwendung einer <T>-Komponente schwieriger.
const t = useGT();
const data = {
title: t('Hallo, Welt!'),
description: t('Das ist eine Beschreibung'),
};Siehe den Leitfaden zu Strings, um mehr über den Hook useGT zu erfahren.
Die Funktion msg
Die Funktion msg wird verwendet, um Zeichenketten zur Übersetzung zu markieren, die in mehreren Komponenten genutzt oder in Konfigurationsobjekten gespeichert werden.
Dies ist besonders nützlich für gemeinsam genutzte Inhalte wie Navigationslabels, Formularmeldungen oder beliebigen Text, der an mehreren Stellen in Ihrer Anwendung erscheint.
// Strings für Übersetzung markieren
import { msg } from 'gt-next';
const navItems = [
{ label: msg('Startseite'), href: '/' },
{ label: msg('Über uns'), href: '/about' },
{ label: msg('Kontakt'), href: '/contact' }
];// Dekodiere und verwende die markierten 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 versieht Zeichenketten mit Übersetzungsmetadaten, und useMessages (oder getMessages für Server-Komponenten) wertet sie aus und stellt sie wieder her.
Weitere Informationen zur Funktion msg finden Sie im Leitfaden zu gemeinsam genutzten Zeichenketten.
Der useTranslations-Hook
Der React-Hook useTranslations gibt eine Funktion zurück, mit der Übersetzungen für einen bestimmten Schlüssel abgerufen werden können.
const dictionary = {
hello: {
world: 'Hallo, Welt!',
},
};const translate = useTranslations();
translate('hallo.welt');Dieses Verhalten ähnelt dem anderer Übersetzungsbibliotheken wie react-i18next und next-intl.
Wir raten davon ab, den Hook useTranslations in Ihrer Anwendung zu verwenden. Die häufige Nutzung von useTranslations erschwert die Wartung Ihrer Codebasis
und führt zu erheblicher technischer Schuld.
Verwenden Sie stattdessen die Komponente <T> oder den Hook useGT.
Wenn Sie von einer anderen i18n-Bibliothek migrieren, ist der Hook useTranslations ein Drop-in-Ersatz und kann bei der schrittweisen Migration Ihrer Codebasis hilfreich sein.
Weitere Informationen zum Hook useTranslations finden Sie im Leitfaden dictionaries.
Ausführlichere Details finden Sie in der useTranslations API Reference.
Nächste Schritte
- Erfahren Sie, wie Sie Ihr Next.js-Projekt mit dem SDK einrichten: Quickstart
- Erfahren Sie, wie Sie JSX-Inhalte mit der Komponente
<T>übersetzen: Leitfaden zur JSX-Übersetzung - Erfahren Sie, wie Sie Strings mit dem Hook
useGTübersetzen: Leitfaden zur String-Übersetzung - Erfahren Sie mehr über Shared Strings mit der Funktion
msg: Leitfaden zu Shared Strings
Wie ist dieser Leitfaden?