Migration
Erfahre, wie du ein Projekt auf gt-next migrierst
Überblick
In diesem Leitfaden zeigen wir 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 derzeit eine andere i18n‑Bibliothek verwendet.
- Grundkenntnisse der
gt-next‑Bibliothek.
Warum migrieren?
Es gibt viele Gründe, dein Projekt auf gt-next zu migrieren.
Hier sind nur einige:
- Keine JSON-Dateien mehr: Verwalte Übersetzungen nie wieder in JSON-Dateien. Dein gesamter Content liegt dort, wo er hingehört: direkt im Code.
- Automatische Übersetzungen: Erzeuge hochwertige, kontextbezogene Übersetzungen mit unserem CLI-Tool (Kommandozeilenwerkzeug). Du musst nie wieder auf Übersetzungen warten.
- Experimentieren in der Entwicklung: Probiere Übersetzungen in der Entwicklung ganz einfach aus – dank Hot-Reloading für Übersetzungen.
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 Projekt-Root eine 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> dem 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 next.config.js-Datei 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 in der Schnellstartanleitung.
An diesem Punkt hast du 3 Optionen:
- Migriere dein gesamtes Projekt vollständig zu
gt-nextund entferne die alte i18n-Bibliothek. - Migriere dein Projekt vollständig, verwende aber weiterhin Dictionaries aus der alten i18n-Bibliothek.
- Verwende vorerst weiterhin die alte i18n-Bibliothek und migriere nur einen Teil deines Projekts zu
gt-next.
Weitere Details zu jeder Option 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 im Code nach allen Vorkommen von useTranslations und ersetzen Sie sie durch useGT.
Anschließend müssen Sie alle String‑Keys 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>
}Wiederholen Sie dies für alle Vorkommen Ihrer alten i18n‑Bibliothek.
Option 2: Migrieren Sie Ihr Projekt vollständig, verwenden Sie aber weiterhin Wörterbücher aus der alten i18n‑Bibliothek
Angenommen, Sie möchten Ihr Projekt auf gt-next migrieren, aber weiterhin Wörterbücher aus der alten i18n‑Bibliothek verwenden und GT Inline‑Features nur für neue Inhalte nutzen.
In diesem Fall können Sie ähnlich wie bei Option 1 vorgehen:
Suchen Sie alle Verwendungen Ihrer alten i18n‑Bibliothek, etwa 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 kann auf die gleiche Weise verwendet werden.
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 Wörterbuchdatei in diese neue Datei.
Die Initialisierungsfunktion withGTConfig in next.config.js erkennt die Wörterbuchdatei im Projektstamm oder im Verzeichnis src automatisch.
Weitere Details finden Sie im Leitfaden zu dictionaries.
Option 3: Vorerst die alte i18n-Bibliothek weiterverwenden und nur einen Teil deines Projekts auf gt-next migrieren
Diese Option ist am flexibelsten und erfordert auf einen Schlag die wenigsten Codeänderungen.
In diesem Fall kannst du ähnlich wie bei Option 2 vorgehen, aber nur einen Teil deines Projekts auf gt-next migrieren.
Zum Beispiel kannst du für einige Komponenten weiterhin die alte i18n-Bibliothek verwenden und gt-next nur für andere Komponenten sowie für neue Inhalte einsetzen.
Diese Option wird nicht empfohlen, da du zwei unterschiedliche i18n-Bibliotheken in deinem Projekt verwalten musst, was komplex sein kann und zu Fehlern führen kann.
Migrationshinweise
1. Nutzen Sie den useGT-Hook oder die <T>-Komponente so oft wie möglich
Wo immer es geht, empfehlen wir, den useGT-Hook oder die <T>-Komponente zu verwenden.
Das erleichtert das spätere Bearbeiten Ihrer Inhalte erheblich und macht Ihre Codebase deutlich besser lesbar.
2. Verwenden Sie den useTranslations-Hook für bestehende Inhalte
Der useTranslations-Hook ist eine hervorragende Möglichkeit, Ihre bestehenden dictionaries weiterzuverwenden.
Wir bieten ihn an, um die Migration zu erleichtern, empfehlen ihn jedoch nicht für neue Inhalte.
3. Verwendung von KI
Wenn Sie KI zur Unterstützung der Migration Ihres Projekts einsetzen, stellen wir die Dateien LLMs.txt und LLMs-full.txt hier bereit:
Wie ist diese Anleitung?