Panoramica

withGTConfig è il metodo principale per configurare la libreria gt-next. Avvolge direttamente un oggetto NextConfig.

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

const nextConfig = {
    // il tuo next.config.js esistente
}

export default withGTConfig(nextConfig, {
  // Opzioni di configurazione aggiuntive
});

Usa withGTConfig per:

• Configurare le lingue supportate e la locale predefinita (cioè la lingua di fallback).
• Impostare le chiavi API e gli ID di progetto per accedere ai servizi GT.
• Definire il comportamento di caricamento.
• Configurare le impostazioni di timeout.
• Impostare endpoint personalizzati.
• Personalizzare il comportamento di traduzione, la cache e il batching delle richieste.
• Abilitare la convalida in fase di build tramite il plugin SWC.

Riferimento

Per impostazione predefinita, withGTConfig cercherà un file gt.config.json nella stessa directory del file next.config.js.

Questo file JSON verrà caricato e unito alla configurazione passata a withGTConfig.

Consulta la documentazione di gt.config.json per ulteriori informazioni sul file di configurazione.

Proprietà obbligatorie

Proprietà consigliate

Prop avanzati

Restituisce

Una funzione (NextConfig) => NextConfig che estende l'oggetto di configurazione di Next.js con le impostazioni di GT specificate.

Eccezioni

Genera un Error se projectId è assente e si usano gli URL predefiniti, oppure se la chiave API è necessaria ma non è presente.

Impostazioni di rendering

Le impostazioni di rendering controllano il comportamento delle traduzioni durante il caricamento. Questo si applica solo alle traduzioni eseguite a runtime. Se la traduzione è in cache, il tempo di risposta è troppo breve per giustificare un comportamento di caricamento.

Metodi di rendering

• skeleton: Effettua il rendering di un frammento.
• replace: Mostra il contenuto nella lingua predefinita durante l’attesa.
• default: Per le varianti con la stessa lingua (es. en-US e en-GB) si comporta come replace. Per le varianti con lingue diverse (es. en-US e fr) si comporta come skeleton.

Timeout

I timeout si applicano solo alle traduzioni in runtime, ossia a quelle che devono essere eseguite su richiesta perché non sono state memorizzate nella cache.

Per impostazione predefinita, i timeout sono di 8 secondi. Questa scelta progettuale è pensata per agevolare gli utenti di Vercel, che sul piano gratuito hanno un timeout predefinito di 10 secondi per le funzioni serverless.

Esempi

Impostazioni di rendering

Questo esempio configura gt-next per mostrare uno scheletro mentre si attendono le traduzioni. Se il caricamento delle traduzioni supera gli 8 secondi, il metodo va in timeout e viene mostrato il contenuto nella lingua predefinita.

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

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

const nextConfig = {
  // Le tue altre configurazioni Next.js
};

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

Validazione in fase di build

Questo esempio configura il plugin SWC per considerare le violazioni di contenuto dinamico come errori di build invece che semplici avvisi.

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

const nextConfig = {
  // Le tue altre configurazioni Next.js
};

export default withGTConfig(nextConfig, {
  // Interrompi la build in caso di violazioni JSX dinamiche
  dynamicJsxCheckLogLevel: 'error',
  // Avvisa in caso di violazioni di stringhe dinamiche  
  dynamicStringCheckLogLevel: 'warn',
});

Note

• withGTConfig integra la funzionalità di traduzione di GT nella tua app Next.js e deve essere utilizzato nel file di configurazione principale.
• Parametri come apiKey e projectId possono essere definiti direttamente nella configurazione o come variabili d’ambiente.
• Parametri avanzati come renderSettings e _batchInterval consentono un controllo fine del comportamento e delle prestazioni della traduzione.

Prossimi passi

• Aggiungi la traduzione al processo di CD.