Config

withGTConfig()

API-Referenz für withGTConfig(), ehemals initGT()

Übersicht

withGTConfig() ist die primäre Methode, um die gt-next-Bibliothek zu konfigurieren. Es umschließt direkt ein NextConfig-Objekt.

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

const nextConfig = {
    // your existing next.config.js
}

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

Veraltet

initGT() ist die veraltete Methode, um die gt-next-Bibliothek zu konfigurieren. Sie gibt einen Funktions-Callback zurück, der dann auf das NextConfig-Objekt angewendet wird. Die Props für beide Funktionen sind gleich, mit der Ausnahme, dass withGTProps erfordert, dass auch NextConfig übergeben wird.

Verwenden Sie withGTConfig(), um:

  • Unterstützte Sprachen und die Standard-Lokalisierung (auch Fallback-Sprache genannt) zu konfigurieren.
  • API-Schlüssel und Projekt-IDs für den Zugriff auf GT-Dienste festzulegen.
  • Das Ladeverhalten einzustellen.
  • Timeout-Einstellungen zu konfigurieren.
  • Eigene Endpunkte einzurichten.
  • Das Übersetzungsverhalten, Caching und das Batching von Anfragen anzupassen.

withGTConfig() muss in Ihrer next.config.js-Datei verwendet werden, um die Übersetzungsfunktionalität zu aktivieren.

Referenz

Standardmäßig sucht withGTConfig() nach einer gt.config.json Datei im selben Verzeichnis wie Ihre next.config.js Datei.

Diese JSON-Datei wird geladen und mit der Konfiguration zusammengeführt, die an withGTConfig() übergeben wird.

Siehe die gt.config.json Referenz für weitere Informationen zur Konfigurationsdatei.

Das CLI-Tool liest die Konfiguration nur aus der gt.config.json Datei, daher empfehlen wir, die gt.config.json Datei als einzige Quelle der Wahrheit für Ihre App zu verwenden.

Zusätzliche Konfigurationsoptionen, die nicht in der gt.config.json Datei enthalten sind, können direkt als Props an withGTConfig() übergeben werden.

Erforderliche Props

PropTypeDefault
nextConfig?
NextConfig
-

Empfohlene Props

PropTypeDefault
description??
string
undefined
locales??
string[]
undefined
defaultLocale??
string
locales[0] || 'en'
PropBeschreibung
defaultLocaleStandard-Locale für die Anwendung. Englisch wird die Fallback-Sprache sein, wenn keine angegeben ist.
localesEine exklusive Liste der unterstützten Locales für die Anwendung. Wenn eine nicht unterstützte Anfrage empfangen wird, wird zur nächstbevorzugten Sprache des Browsers in der Liste umgeleitet. Fällt auf defaultLocale zurück, wenn keine Übereinstimmungen gefunden werden können.
descriptionEine natürlichsprachliche Beschreibung der Website, die zur Unterstützung der Übersetzung verwendet wird.

Erweiterte Props

PropTypeDefault
dictionary??
string
-
maxBatchSize??
number
25
batchInterval??
number
50
maxConcurrentRequests??
number
100
renderSettings??
RenderSettings
-
cacheExpiryTime??
number
60000
cacheUrl??
string
-
runtimeUrl??
string
-
preferredModelProvider??
"anthropic" | "openai"
-
devApiKey??
string
-
apiKey??
string
-
projectId??
string
-
PropBeschreibung
projectIdProjekt-ID, die hier oder als Umgebungsvariable angegeben werden kann.
apiKeyObwohl nicht empfohlen, ein API-Schlüssel, der hier angegeben werden kann. Er kann auch als Umgebungsvariable angegeben werden.
devApiKeyObwohl nicht empfohlen, ein Entwicklungs-API-Schlüssel, der hier angegeben werden kann. Er kann auch als Umgebungsvariable angegeben werden.
preferredModelProviderIhr bevorzugter KI-Modellanbieter. Derzeit sind nur Anthropic oder OpenAI aktiviert. Lassen Sie dies leer und wir ermitteln den besten Anbieter für jede einzelne Übersetzung. In Zeiten hoher Nutzung oder wenn ein Anbieter deaktiviert ist, können wir nicht garantieren, dass Ihr bevorzugter Anbieter verwendet wird.
runtimeUrlBasis-URL für die GT API. Um die automatische Übersetzung zu deaktivieren, setzen Sie dies auf einen leeren String.
cacheUrlURL, wo zwischengespeicherte Übersetzungen gespeichert werden. Kann angepasst werden, um auf einen benutzerdefinierten Cache-Server zu verweisen.
cacheExpiryTimeZeit in Millisekunden, bevor lokal zwischengespeicherte Übersetzungen ablaufen.
renderSettingsEin Objekt, das das Ladeverhalten für Laufzeit-Übersetzungen spezifiziert.
maxConcurrentRequestsMaximale Anzahl gleichzeitiger Übersetzungsanfragen, die an die GT API erlaubt sind.
maxBatchSizeMaximale Anzahl von Übersetzungen, die zusammengefasst werden, bevor eine Anfrage gesendet wird.
batchIntervalIntervall in Millisekunden zwischen zusammengefassten Übersetzungsanfragen. Hilft dabei, die Rate zu kontrollieren, mit der Anfragen gesendet werden.
dictionaryOptionale Konfigurationsdateipfad für das Wörterbuch. Ähnlich wie i18n akzeptiert es einen String zur Angabe eines benutzerdefinierten Pfads. Wörterbücher namens dictionary.js (oder .jsx, .ts, .tsx etc.), die im Stammverzeichnis oder im src-Ordner platziert werden, werden standardmäßig unterstützt.

Rückgabe

Eine Funktion (NextConfig) => NextConfig, die das Next.js-Konfigurationsobjekt mit den angegebenen GT-Einstellungen erweitert.

Ausnahmen

Wirft einen Error, wenn die projectId fehlt und Standard-URLs verwendet werden, oder wenn der API-Schlüssel erforderlich ist und fehlt.


Render-Einstellungen

Die Render-Einstellungen steuern das Verhalten von Übersetzungen, während sie geladen werden. Dies gilt nur für Übersetzungen, die zur Laufzeit stattfinden. Wenn die Übersetzung zwischengespeichert ist, ist die Antwortzeit zu gering, um ein Ladeverhalten zu rechtfertigen.

PropTypeDefault
timout?
number
8000
method?
"skeleton" | "replace" | "default"
default
PropBeschreibung
methodDie Methode, die zum Rendern der Seite verwendet wird. Optionen sind skeleton, replace und default.
timeoutDie Zeit in Millisekunden, bevor die Methode abläuft. Standardwert ist 8000 ms.

Render-Methoden

  • skeleton: Rendert ein Fragment.
  • replace: Rendert den Inhalt in der Standardsprache, während gewartet wird.
  • default: Für Sprachvarianten mit derselben Sprache (z. B. en-US und en-GB) verhält sich wie replace. Für Sprachvarianten mit unterschiedlichen Sprachen (z. B. en-US und fr) verhält sich wie skeleton.

Timeout

Timeouts gelten nur für Übersetzungen zur Laufzeit oder Übersetzungen, die bei Bedarf durchgeführt werden müssen, da sie nicht zwischengespeichert wurden.

Timeouts sind standardmäßig auf 8 Sekunden gesetzt. Diese Designentscheidung soll Vercel-Nutzern entgegenkommen, die im kostenlosen Tarif ein Standard-Timeout von 10 Sekunden für serverlose Funktionen haben.


Beispiele

Render-Einstellungen

Dieses Beispiel konfiguriert gt-next so, dass ein Skeleton gerendert wird, während auf das Laden der Übersetzungen gewartet wird. Wenn die Übersetzung länger als 8 Sekunden dauert, läuft die Methode ab und rendert den Inhalt der Standardsprache.

gt.config.json
{
  "defaultLocale": "en-US",
  "locales": ["en-US", "es", "fr"],
}
next.config.mjs
import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Your other next.js configurations
};

export default withGTConfig(nextConfig, {
  renderSettings: {
    method: 'skeleton',
    timeout: 10000,
  },
});

Hinweise

  • withGTConfig() integriert die GT-Übersetzungsfunktionalität in deine Next.js-App und muss in der Root-Konfigurationsdatei verwendet werden.
  • Parameter wie apiKey und projectId können direkt in der Konfiguration oder als Umgebungsvariablen gesetzt werden.
  • Erweiterte Parameter wie renderSettings und _batchInterval ermöglichen eine fein abgestimmte Kontrolle über das Übersetzungsverhalten und die Performance.

Nächste Schritte

Wie ist dieser Leitfaden?