Migration
Erfahren Sie, wie Sie ein Projekt auf gt-next migrieren.
Überblick
Dieser Leitfaden führt Sie durch die Schritte, um ein Projekt, das bereits eine i18n-Bibliothek verwendet, auf gt-next zu migrieren.
Außerdem geben wir Tipps und Empfehlungen, wie Sie die Migration so reibungslos wie möglich gestalten.
Voraussetzungen
- Ein Projekt, das aktuell eine andere i18n-Bibliothek verwendet.
- Grundlegende Kenntnisse der Bibliothek
gt-next.
Warum migrieren?
Es gibt viele Gründe, Ihr Projekt auf gt-next zu migrieren.
Hier sind nur einige:
- Keine JSON-Dateien mehr: Verwalten Sie Übersetzungen nie wieder in JSON-Dateien. Ihr gesamter Inhalt befindet sich direkt in Ihrem Code – dort, wo er hingehört.
- Automatische Übersetzungen: Erzeugen Sie hochwertige, kontextbezogene Übersetzungen mit unserem CLI-Tool. Sie müssen nie wieder auf Übersetzungen warten.
- Experimentieren in der Entwicklung: Experimentieren Sie in der Entwicklung ganz einfach mit Übersetzungen dank Hot-Reloading.
Einrichtung
Installiere gt-next und das CLI-Tool gtx-cli.
npm i gt-next gtx-cliyarn add gt-next
yarn add --dev gtx-clibun add gt-next
bun add --dev gtx-clipnpm add gt-next
pnpm add --save-dev gtx-cliErstelle im Projektstamm die Datei gt.config.json mit der Eigenschaft defaultLocale und einem Array locales.
{
"defaultLocale": "en",
"locales": ["en", "fr", "es"]
}Füge anschließend die Komponente <GTProvider> zum Root-Layout deiner App hinzu.
import { GTProvider } from 'gt-next'
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
)
}Füge als Nächstes withGTConfig zu deiner Datei next.config.js hinzu.
import withGTConfig from 'gt-next/config'
const nextConfig = {
// Your next.config.ts options
}
export default withGTConfig(nextConfig, {
// Your GT configuration
})Ausführlichere Schritte findest du im Quickstart-Guide.
An diesem Punkt hast du drei Optionen:
- Migriere dein gesamtes Projekt vollständig zu
gt-nextund entferne die alte i18n-Bibliothek. - Migriere dein Projekt vollständig, nutze aber weiterhin Dictionaries der alten i18n-Bibliothek.
- Nutze vorerst weiterhin die alte i18n-Bibliothek und migriere nur einen Teil deines Projekts zu
gt-next.
Weitere Details zu den einzelnen Optionen findest du im Abschnitt Migrationsstrategien.
Migrationsstrategien
Option 1: Migrieren Sie Ihr gesamtes Projekt vollständig
Diese Option ist am unkompliziertesten, erfordert jedoch auch die meisten Codeänderungen auf einmal.
Nachdem Sie Ihr Projekt eingerichtet haben, müssen Sie alle Vorkommen Ihrer bisherigen i18n-Bibliothek suchen und durch gt-next ersetzen.
Wenn Ihre App React Hooks wie useTranslations verwendet, suchen Sie in Ihrem Code nach allen Vorkommen von useTranslations und ersetzen Sie sie durch useGT.
Anschließend müssen Sie alle String-Schlüssel durch ihre tatsächlichen String-Werte ersetzen.
Wenn Ihr alter Code beispielsweise so aussieht:
{
"hello": {
"description": "Hallo, Welt!"
}
}export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}Sie müssen es durch Folgendes ersetzen:
export default function MyComponent() {
const t = useGT()
return <div>{t('Hallo, Welt!')}</div>
}
// OR
export default function MyComponent() {
return <T>Hallo, Welt!</T>
}Führen Sie dies für alle Vorkommen Ihrer alten i18n‑Bibliothek aus.
Option 2: Migrieren Sie Ihr Projekt vollständig, verwenden Sie aber weiterhin Dictionaries aus der alten i18n-Bibliothek
Angenommen, Sie möchten Ihr Projekt auf gt-next migrieren, aber weiterhin Dictionaries aus der alten i18n-Bibliothek verwenden und GT Inline-Funktionen nur für neue Inhalte nutzen.
In diesem Fall können Sie ähnlich wie in Option 1 vorgehen:
Suchen Sie alle Vorkommen Ihrer alten i18n-Bibliothek, z. B. useTranslations-Hooks, und ersetzen Sie sie durch useTranslations-Hooks aus gt-next.
Der useTranslations-Hook verhält sich sehr ähnlich wie useTranslations-Hooks in anderen i18n-Bibliotheken, und Sie können ihn auf die gleiche Weise verwenden.
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
const { t } = useTranslation()
return <div>{t('hello.description')}</div>
}import { useTranslations } from 'gt-next'
export default function MyComponent() {
const t = useTranslations()
return <div>{t('hello.description')}</div>
}Für die Konfiguration müssen Sie eine Datei dictionary.[js|ts|json] im Projektstamm oder im Verzeichnis src erstellen.
Kopieren Sie den Inhalt Ihrer alten Dictionary-Datei in diese neue Datei.
Die Initialisierungsfunktion withGTConfig in next.config.js erkennt die Dictionary-Datei im Projektstamm oder im Verzeichnis src automatisch.
Weitere Details finden Sie im Guide dictionaries.
Option 3: Vorerst die alte i18n-Bibliothek weiterverwenden und nur einen Teil Ihres Projekts auf gt-next migrieren
Diese Option ist am flexibelsten und erfordert auf einen Schlag die wenigsten Codeänderungen.
In diesem Fall können Sie ähnlich wie bei Option 2 vorgehen, jedoch nur einen Teil Ihres Projekts auf gt-next migrieren.
Beispielsweise können Sie die alte i18n-Bibliothek für manche Komponenten beibehalten und gt-next nur für andere sowie für neue Inhalte verwenden.
Diese Option wird nicht empfohlen, da Sie zwei unterschiedliche i18n-Bibliotheken in Ihrem Projekt verwalten müssten, was komplex sein und zu Fehlern führen kann.
Migrationshinweise
1. Verwenden Sie den Hook useGT oder die Komponente <T> so häufig wie möglich
Wo immer möglich, empfehlen wir, den Hook useGT oder die Komponente <T> zu verwenden.
So wird das Bearbeiten Ihrer Inhalte in Zukunft deutlich einfacher und der Code deutlich besser lesbar.
2. Verwende den Hook useTranslations für vorhandene Inhalte
Der Hook useTranslations ist eine hervorragende Möglichkeit, deine bestehenden dictionaries weiterzuverwenden.
Wir bieten ihn an, um die Migration zu erleichtern, empfehlen jedoch nicht, ihn für neue Inhalte zu verwenden.
3. Verwendung von KI
Wenn Sie KI zur Unterstützung bei der Migration Ihres Projekts einsetzen, stellen wir die Dateien LLMs.txt und LLMs-full.txt unter folgenden Links bereit:
Wie ist dieser Leitfaden?