Introduzione

La libreria generaltranslation è la libreria i18n principale di GT e include funzioni e classi per la traduzione e la formattazione. È usata più spesso insieme a framework come gt-next e gt-react, ma può essere utilizzata anche come libreria autonoma.

import { GT } from 'generaltranslation';

const gt = new GT({
  apiKey: 'la tua API key',
  projectId: 'il tuo project ID',
  sourceLocale: 'en',
  targetLocale: 'es',
});

// Traduci contenuti
const result = await gt.translate('Hello, world!', 'es');
// "¡Hola, mundo!"

// Formatta numeri, date e valute
const formattedPrice = gt.formatCurrency(29.99, 'USD');
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "9/25/2025"

// Lavora con le impostazioni locali
const localeProps = gt.getLocaleProperties('fr-CA');
const isValid = gt.isValidLocale('de');
// { language: "fr", region: "CA", ... }
// true

Installazione

npm install generaltranslation

yarn add generaltranslation

bun add generaltranslation

pnpm add generaltranslation

Esempi

Esistono due tipi principali di traduzione: traduzione di stringhe e traduzione di file.

Configurazione

Per abilitare la traduzione, devi fornire un ID del progetto e una chiave API. Consulta il metodo constructor per ulteriori informazioni.

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  targetLocale: 'es',
});

Traduzione delle stringhe

Per maggiori dettagli, vedi il metodo translate.

try {
  const result = await gt.translate('Ciao, mondo!');
  console.log(result); // "Ciao, mondo!"
} catch (error) {
  console.error('Traduzione non riuscita:', error.message);
}

Traduzione dei file

I file vengono tradotti tramite job. Avvii un job caricando un file. Caricare molti file avvierà molti job.

Consulta i metodi uploadSourceFiles e checkFileTranslations per ulteriori informazioni.

// File da caricare
const files = [
  {
    source: {
      fileName: 'src/components/Button.tsx',
      fileFormat: 'TSX',
      locale: 'en',
      content: '...',
    },
  },
];

// Carica i file sorgente
await gt.uploadSourceFiles(files);

Sommario

Classe GT

Classe principale per le funzionalità di traduzione e di gestione dei locali/lingue:

• Constructor - Inizializza un'istanza di GT con la configurazione
• setConfig - Aggiorna la configurazione dell'istanza di GT

Metodi di traduzione

• translate - Funzionalità principale di traduzione
• translateMany - Traduzione in batch
• setupProject - Inizializzazione del progetto
• shouldSetupProject - Verifica se è necessaria la configurazione del progetto
• checkSetupStatus - Verifica dello stato della configurazione del progetto
• getProjectData - Recupera i dati del progetto
• uploadSourceFiles - Carica i file da tradurre
• enqueueFiles - Mette in coda i file per l’elaborazione
• checkFileTranslations - Controlla lo stato delle traduzioni
• downloadTranslatedFile - Scarica un singolo file tradotto
• downloadFileBatch - Scarica più file tradotti
• querySourceFile - Interroga i metadati del file sorgente

Metodi di formattazione

• formatMessage - Formattazione di testi internazionalizzati
• formatNum - Formattazione dei numeri
• formatDateTime - Formattazione di data e ora

Metodi sulle locale

• getLocaleName - Ottieni il nome visualizzato della locale
• getLocaleProperties - Ottieni informazioni complete sulla locale
• getLocaleDirection - Ottieni la direzione del testo per la locale
• getLocaleEmoji - Ottieni l’emoji della bandiera per la locale
• getRegionProperties - Ottieni informazioni e proprietà della regione
• isValidLocale - Convalida il codice locale
• resolveAliasLocale - Converti le locale canoniche in alias
• resolveCanonicalLocale - Converti le locale alias in forma canonica
• standardizeLocale - Normalizza la formattazione del codice locale
• isSameDialect - Verifica se le locale rappresentano lo stesso dialetto
• isSameLanguage - Verifica se le locale rappresentano la stessa lingua
• isSupersetLocale - Verifica le relazioni gerarchiche tra locale
• determineLocale - Trova la locale migliore in base alle preferenze
• requiresTranslation - Determina se è necessaria una traduzione

Funzioni di utilità

Funzioni di formattazione

• formatMessage - Formattazione del testo indipendente
• formatNum - Formattazione dei numeri indipendente
• formatDateTime - Formattazione di data/ora indipendente

Funzioni per le locale

• getLocaleName - Utility autonoma per il nome della locale
• getLocaleProperties - Proprietà della locale (standalone)
• getLocaleDirection - Utility autonoma per la direzione del testo
• getLocaleEmoji - Utility autonoma per l’emoji della locale
• getRegionProperties - Utility autonoma per le proprietà della regione
• isValidLocale - Validazione della locale (standalone)
• resolveAliasLocale - Risoluzione autonoma degli alias di locale
• standardizeLocale - Standardizzazione della locale (standalone)
• isSameDialect - Confronto autonomo tra dialetti
• isSameLanguage - Confronto autonomo tra lingue
• isSupersetLocale - Verifica autonoma della gerarchia delle locale
• determineLocale - Negoziazione autonoma della locale
• requiresTranslation - Verifica autonoma della necessità di traduzione

Tipi e interfacce

Definizioni TypeScript:

• GTConstructorParams - Opzioni di configurazione
• LocaleProperties - Informazioni complete sulla locale
• TranslationResult - Tipi di risposta della traduzione
• TranslateManyResult - Risposta per traduzioni in batch
• FileToTranslate - Configurazione della traduzione dei file
• EnqueueFilesOptions - Opzioni di messa in coda dei file
• Entry - Struttura della voce di traduzione
• EntryMetadata - Metadati della voce
• Content - Definizioni dei tipi di contenuto
• Variable - Struttura della variabile
• VariableType - Definizioni dei tipi di variabile
• JsxElement - Tipo di elemento JSX
• JsxChild - Tipo di nodo figlio JSX
• JsxChildren - Tipo dei nodi figli JSX
• DataFormat - Specifiche del formato dei dati
• CustomMapping - Configurazione del mapping personalizzato

Prossimi passi

• Inizia con la classe GT
• Esplora i metodi di traduzione
• Scopri le utility per le impostazioni locali
• Scopri le opzioni di formattazione
• Sfoglia le funzioni autonome

Per l’uso specifico del framework, consulta la documentazione di Next.js o React.