Next.js Schnellstart

Übersicht

Diese Schnellstartanleitung führt Sie durch die Einrichtung Ihrer Next.js-Anwendung mit gt-next.

Am Ende dieser Anleitung haben Sie eine Next.js-App, die bereit ist, Inhalte zu übersetzen.

In dieser Anleitung behandeln wir Folgendes:

Installation

Konfiguration

Verwendung

Testen Ihrer App

Bereitstellung

Voraussetzungen

Eine Next.js-Anwendung, die den App Router verwendet
Grundkenntnisse in Next.js und JavaScript

Installation

Installieren Sie die gt-next und gtx-cli Pakete:

npm i gt-next
npm i --save-dev gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

Automatische Einrichtung: Wir haben einen experimentellen Setup-Assistenten, der Ihnen bei der Einrichtung Ihres Projekts mit gt-next helfen kann.

Probieren Sie ihn aus, indem Sie npx gtx-cli@latest ausführen. Sie müssen Strings weiterhin manuell internationalisieren, aber er hilft Ihnen beim Einstieg.

Weitere Informationen finden Sie im Referenzhandbuch für den Setup-Assistenten.

Alternativ können Sie, wenn Sie möchten, dass Ihr KI-Tool wie Claude Code, Cursor oder Windsurf Ihr Projekt automatisch einrichtet, unseren mcp server verwenden.

Konfiguration

`withGTConfig`

Die withGTConfig Funktion ist eine Funktion, die verwendet wird, um das SDK in einer Next.js Anwendung zu initialisieren.

Platzieren Sie dies in Ihrer next.config.[js|ts] Datei.

next.config.ts

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

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

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

Siehe die withGTConfig API Referenz für weitere Informationen.

`GTProvider`

gt-next exportiert auch eine GTProvider Komponente. Diese Komponente wird verwendet, um Kontext für clientseitige Komponenten in Ihrer Next.js Anwendung bereitzustellen.

Der GTProvider und withGTConfig arbeiten zusammen, um Kontext für Ihre Anwendung bereitzustellen.

Dieser Kontext umfasst:

Verwaltung der aktuellen Sprache des Benutzers
Die relevanten Übersetzungen für diese Sprache
Kontext für den useGT Hook
Kontext für den useTranslations Hook

Fügen Sie zunächst die GTProvider Komponente zum Root-Layout Ihrer Anwendung hinzu. Sie sollte so hoch wie möglich in Ihrem Komponentenbaum platziert werden.

src/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

Wenn Sie mehrere Root-Layouts haben, platzieren Sie den GTProvider in jedem von ihnen.

Erstellen Sie als nächstes eine gt.config.json Datei im Stammverzeichnis Ihres Projekts. Diese Datei wird verwendet, um sowohl das gtx-cli Tool als auch die gt-next Bibliothek zu konfigurieren.

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}

Sie sollten die defaultLocale und locales an Ihr Projekt anpassen. Siehe die Liste der unterstützten Sprachen für weitere Informationen.

withGTConfig erkennt automatisch die gt.config.json Datei in Ihrem Projekt und verwendet sie zur Konfiguration des SDK.

Umgebungsvariablen

Setzen Sie die folgenden Umgebungsvariablen:

GT_API_KEY="" # Your General Translation Developer API key
GT_PROJECT_ID="" # Your General Translation project ID

Stellen Sie sicher, dass Ihre API-Schlüssel-Variable nur in Ihrer Entwicklungsumgebung gesetzt ist! Sie sollte nicht in der Produktion gesetzt werden.

Sie können einen kostenlosen API-Schlüssel und eine Projekt-ID erhalten, indem Sie ein General Translation Konto erstellen.

Nach der Kontoerstellung navigieren Sie zur Seite Development API Keys, um Ihren Dev API-Schlüssel und Ihre Projekt-ID zu erhalten.

Alternativ können Sie auch den CLI-Tool-Befehl npx gtx-cli auth verwenden, um einen API-Schlüssel und eine Projekt-ID für Ihr Projekt zu generieren, die in Ihrer .env.local Datei gespeichert werden.

Verwendung

Großartig! Wenn Sie die obigen Schritte befolgt haben, ist Ihre Next.js-App jetzt für die Verwendung von gt-next eingerichtet.

Der nächste Schritt ist die Internationalisierung Ihrer Inhalte. Hier geben wir einen kurzen Überblick über die verschiedenen Möglichkeiten, Inhalte in Ihrer Anwendung zu übersetzen.

`<T>` Component

Die <T> Component ist die Hauptkomponente für die Übersetzung von JSX-Inhalten in Ihrer Anwendung.

Um sie zu verwenden, umhüllen Sie einfach das JSX, das Sie übersetzen möchten, mit der <T> Component.

import { T } from 'gt-next';
<T>
  <div>Your content</div>
</T>

Wenn Sie dynamische Inhalte haben, müssen Sie variable components verwenden, um die dynamischen Werte zu übergeben.

import { T, Var } from 'gt-next';

<T>
  <div>Hello, <Var>{name}</Var>!</div>
</T>

Weitere Informationen finden Sie im Translating JSX Leitfaden.

`useGT` Hook

Der useGT Hook ist ein React Hook, der eine Funktion zurückgibt, die zur Übersetzung von Strings verwendet werden kann.

import { useGT } from 'gt-next'

const translate = useGT();
translate('Hello, world!');

Der useGT Hook kann sowohl in client-seitigen als auch in server-seitigen Komponenten verwendet werden. Für asynchrone Komponenten verwenden Sie stattdessen die asynchrone getGT() Funktion.

Weitere Informationen finden Sie im Translating Strings Leitfaden.

Die Nutzung der Hot-Reload-Übersetzungsfunktionalität wird bei der Internationalisierung Ihrer Anwendung hilfreich sein.

Um dies zu aktivieren, stellen Sie sicher, dass Sie die Umgebungsvariablen GT_API_KEY und GT_PROJECT_ID in Ihrer Entwicklungsumgebung gesetzt haben.

Testen Ihrer App

Herzlichen Glückwunsch! 🥳 Wenn Sie die obigen Schritte befolgt haben, ist Ihre App jetzt mehrsprachig! Sehen wir uns das Ergebnis an.

Ihre App in einer anderen Sprache anzeigen

Fügen Sie die <LocaleSelector> Komponente zu Ihrer App hinzu. Damit können Sie eine andere Sprache für Ihre App auswählen.

Tipp: Sie können diesen Schritt auch überspringen und einfach Ihre Sprache in den Browsereinstellungen ändern.

Starten Sie Ihre Next.js-App im Entwicklungsmodus.

npm run dev

yarn run dev

bun run dev

pnpm run dev

Öffnen Sie Ihre App in Ihrem bevorzugten Browser (in der Regel unter http://localhost:3000).

Fehlerbehebung

Deployment

Super! Wenn Sie mit Ihren Übersetzungen und der Funktionalität Ihrer App zufrieden sind, können Sie Ihre Anwendung jetzt bereitstellen.

Das Verhalten von gt-next in der Produktion unterscheidet sich leicht von der Entwicklung. Insbesondere werden zur Laufzeit keine Übersetzungen mehr durchgeführt (mit Ausnahme der <Tx> Komponente und der tx Funktion).

Das bedeutet, dass Sie Ihre Inhalte vor der Bereitstellung Ihrer Anwendung, also im Build-Prozess, übersetzen müssen.

Glücklicherweise verfügt das gtx-cli Tool über einen translate Befehl, mit dem Sie Ihre Inhalte automatisch übersetzen lassen können.

Zuerst benötigen Sie einen Production API-Schlüssel von der General Translation Plattform.

Bitte beachten Sie, dass sich dieser Schlüssel von Ihrem Development API-Schlüssel unterscheidet und mit gtx-api- beginnt, anstatt mit gtx-dev-.

Lesen Sie mehr über den Unterschied zwischen Development- und Production-Schlüsseln hier.

Fügen Sie diese Umgebungsvariable zu Ihrer CI/CD-Pipeline hinzu.

GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>

Stellen Sie sicher, dass GT_API_KEY NICHT mit NEXT_PUBLIC_ beginnt!

Andernfalls riskieren Sie, Ihren API-Schlüssel öffentlich zugänglich zu machen.

Führen Sie den translate Befehl aus, um Ihre Inhalte zu übersetzen.

npx gtx-cli translate

Sie können das Verhalten des translate Befehls mit der gt.config.json Datei konfigurieren.

Weitere Informationen finden Sie im CLI Tool Referenzhandbuch.

Fügen Sie den translate Befehl zu Ihrem Build-Prozess hinzu.

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Zusammenfassung

In diesem Leitfaden haben wir erklärt, wie du deine Next.js-App mit gt-next einrichtest.
Wir haben kurz die verschiedenen Möglichkeiten vorgestellt, Inhalte in deiner Anwendung zu übersetzen.
Außerdem haben wir erläutert, wie du deine Anwendung bereitstellst, nachdem du deine Inhalte internationalisiert hast.

Nächste Schritte

Erfahren Sie, wie Sie JSX-Inhalte mit der <T>-Komponente übersetzen: JSX übersetzen
Erfahren Sie, wie Sie Zeichenketten mit dem useGT-Hook übersetzen: Zeichenketten übersetzen
Lernen Sie, wie Sie lokale Übersetzungen verwenden: Lokale Übersetzungen

Next.js Schnellstart

Was ist, wenn ich die General Translation Plattform nicht verwenden möchte?

Die Sprache meiner App ändert sich nicht, obwohl ich die Sprache meines Browsers geändert habe.

Warum dauert das Laden der Sprachen im Entwicklungsmodus so lange?

Warum werden manche Dinge übersetzt und andere nicht?

Warum sind einige Übersetzungen ungenau?

What if I'm not using the General Translation platform?

Auf dieser Seite