# gt: General Translation CLI tool: Configurazione URL: https://generaltranslation.com/it/docs/cli/reference/config.mdx --- title: Configurazione description: Documentazione di configurazione del file gt.config.json --- ## Panoramica Il file `gt.config.json` viene usato per configurare le impostazioni di GT del tuo progetto. Deve essere posizionato nella directory radice del progetto. La procedura guidata di setup della CLI [`npx gt init`](/docs/cli/init) creerà automaticamente un file `gt.config.json` nel tuo progetto. ## Configurazione Il file `gt.config.json` accetta le seguenti proprietà, senza tuttavia limitarsi a queste: * `defaultLocale`: L'impostazione regionale predefinita del tuo progetto. È l'impostazione regionale in cui sono scritti i contenuti sorgente. È anche l'impostazione regionale di fallback del progetto (se usi `gt-next` o `gt-react`). * `locales`: Un array di impostazioni regionali per il tuo progetto. Sono le impostazioni regionali in cui vuoi tradurre il progetto. Per ulteriori informazioni, consulta le [impostazioni regionali supportate](/docs/platform/supported-locales). Se usi `gt-next` o `gt-react`, queste sono anche le impostazioni regionali supportate dalla tua app. * `files`: Un oggetto che contiene informazioni sui contenuti che vuoi tradurre. * `publish`: Un flag booleano facoltativo. Quando è `true`, i file tradotti vengono pubblicati sulla CDN di GT dopo l'esecuzione di `translate`, `upload` o `save-local`. Il valore predefinito è `false` (nessuna pubblicazione). Può anche essere impostato per singolo comando con `--publish`. Per i dettagli, consulta [pubblicazione sulla CDN](#cdn-publishing). * `stageTranslations`: Un flag booleano facoltativo che indica se il tuo progetto è configurato per usare la revisione umana. * `src`: Un array facoltativo di pattern glob per i file sorgente. Per impostazione predefinita: ```json [ "src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}", "components/**/*.{js,jsx,ts,tsx}" ] ``` * `dictionary`: Una stringa facoltativa che specifica il percorso relativo del file del dizionario. * `branchOptions`: Un oggetto facoltativo per configurare il monitoraggio delle traduzioni per branch. Per maggiori dettagli, consulta [branching](/docs/cli/branching). Per facilitare la validazione del file `gt.config.json`, puoi usare il [JSON Schema](https://assets.gtx.dev/config-schema.json) per la CLI. Aggiungilo all'inizio del file `gt.config.json`: ```json title="gt.config.json" copy { "$schema": "https://assets.gtx.dev/config-schema.json" } ``` Ecco una struttura di base del file `gt.config.json`: ```json title="gt.config.json" { "$schema": "https://assets.gtx.dev/config-schema.json", "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "..." }, "json": { "include": [...] }, "mdx": { "include": [...] }, "md": { "include": [...] } }, "src": [ "src/**/*.{ts,tsx}", ], "dictionary": "./dictionary.json" } ``` ### Alias delle impostazioni regionali Se vuoi creare un alias per un'impostazione regionale (ad esempio `cn` invece di `zh`), puoi specificare una mappatura personalizzata nel file `gt.config.json`. ```json title="gt.config.json" { "customMapping": { // L'impostazione regionale alias "cn": { "code": "zh" // Il codice locale BCP 47 ufficiale } } } ``` Puoi anche specificare attributi diversi per l'impostazione regionale a cui è assegnato un alias. ```json title="gt.config.json" { "customMapping": { "cn": { "code": "zh", "name": "Mandarin" } } } ``` ### Opzioni per il branch Se vuoi configurare le impostazioni del branch nel file di configurazione, puoi usare l'oggetto `branchOptions`: ```json title="gt.config.json" { "branchOptions": { "enabled": true, "currentBranch": "my-feature-branch", "autoDetectBranches": true, "remoteName": "origin" } } ``` | Proprietà | Descrizione | Predefinito | | -------------------- | -------------------------------------------------------------------------- | ----------- | | `enabled` | Abilita il branching per il progetto | `false` | | `currentBranch` | Imposta il nome del branch corrente invece di rilevarlo automaticamente | `undefined` | | `autoDetectBranches` | Rileva automaticamente le relazioni tra branch (in ingresso e selezionati) | `true` | | `remoteName` | Nome del remote Git usato per il rilevamento dei branch | `"origin"` | I flag della CLI hanno la precedenza sulle opzioni del file di configurazione. Per maggiori dettagli, consulta la [guida al branching](/docs/cli/branching). *** ## `files` ### Tipi di file supportati `files` deve contenere una chiave per ogni tipo di file che vuoi tradurre. Puoi configurare il progetto in modo da combinare diversi tipi di file e tradurli tutti. Al momento supportiamo i seguenti tipi di file: * `gt`: file di General Translation. Utilizzati da [`gt-next`](/docs/next), [`gt-react`](/docs/react) e [`gt-react-native`](/docs/react-native). * `json`: file JSON. * `pot`: file PO/POT (gettext). * `yaml`: file YAML. * `mdx`: file Markdown con componenti (MDX). * `md`: file Markdown (MD). * `js`: file JavaScript. * `ts`: file TypeScript. * `html`: file HTML. * `txt`: file di testo. * `twilioContentJson`: file JSON di Twilio Content. Utilizzati per tradurre i [Twilio Content Templates](https://www.twilio.com/docs/content). Ogni tipo di file deve corrispondere a un oggetto che contiene una o più delle seguenti chiavi: * `include` * `exclude` * `transform` * `transformationFormat` * `output` ### `include` Se usata, il valore della chiave `include` deve essere un array di pattern glob che corrispondono ai file che vuoi tradurre. Devi usare il segnaposto `[locale]` nei pattern glob per assicurarti che i file di origine vengano trovati correttamente e che i file tradotti vengano salvati nel percorso corretto. Lo strumento CLI sostituirà il segnaposto `[locale]` con il valore di `defaultLocale` durante la ricerca dei file da tradurre. Lo strumento CLI salverà i file tradotti nel percorso corrispondente, sostituendo il segnaposto `[locale]` con il codice locale di destinazione. ```json { "include": ["docs/[locale]/**/*.json"] } ``` ### `exclude` Se utilizzato, il valore della chiave `exclude` deve essere un array di pattern glob che corrispondono ai file da escludere dalla traduzione. Il pattern è lo stesso di `include`, con la sola eccezione che il segnaposto `[locale]` è facoltativo. Se specificato, verrà sostituito con il valore di `defaultLocale`. ```json { "exclude": ["docs/[locale]/exclude/**/*.json"] } ``` Se vuoi escludere i file dalla traduzione per tutte le impostazioni regionali, puoi usare il segnaposto `[locales]` invece di `[locale]`. ```json { "exclude": ["docs/[locales]/exclude/**/*.json"] } ``` ### `transform` `transform` può essere una stringa oppure un oggetto. Se `transform` è una stringa, definisce una rimappatura del nome del file. Deve contenere un carattere jolly `*`, che verrà sostituito con il nome originale del file (tutto ciò che precede il primo `.`). Ad esempio, se vuoi che l'estensione di tutti i file tradotti sia `.[locale].json` anziché `.json`, puoi usare la seguente configurazione: ```json { "transform": "*.[locale].json" } ``` In alternativa, se `transform` è un oggetto, deve contenere le seguenti proprietà: * `match` (facoltativo): un pattern regex per trovare corrispondenze nelle stringhe; supporta i gruppi di acquisizione * `replace` (obbligatorio): stringa o pattern regex con cui sostituire la corrispondenza Entrambi i valori supportano i gruppi di acquisizione regex e vengono applicati al percorso relativo completo del file di output. ```json { "transform": { "match": "^(.*)$", "replace": "{locale}/$1" } } ``` Ad esempio, la configurazione riportata sopra farà sì che i file tradotti vengano salvati in una sottodirectory dell'impostazione regionale di destinazione. #### Segnaposto speciali L'opzione `transform` supporta diversi segnaposto speciali che possono essere usati sia nelle stringhe `match` che in quelle `replace`: * `{locale}`: il segnaposto del codice locale, che si comporta in modo diverso a seconda del contesto: * **Nelle stringhe `match`**: viene sostituito con il codice locale predefinito (ad esempio `"en"`) per aiutare a identificare i file di origine * **Nelle stringhe `replace`**: viene sostituito con il codice locale di destinazione (ad esempio `"fr"`, `"es"`) per i file tradotti in output Ad esempio, se la tua impostazione regionale predefinita è `"en"` e stai traducendo in `"fr"`: * Un pattern `match` come `"content/{locale}/file.md"` diventa `"content/en/file.md"` * Un pattern `replace` come `"content/{locale}/file.md"` diventa `"content/fr/file.md"` Inoltre, qualsiasi altra proprietà di `getLocaleProperties` può essere usata come segnaposto con lo stesso comportamento dipendente dal contesto. Questo è utile se la tua documentazione o il tuo framework i18n richiede un'estensione di file specifica per i file tradotti invece di un routing delle impostazioni regionali basato su sottodirectory. ### `transformationFormat` La chiave `transformationFormat` specifica un formato di file diverso per i file di output tradotti. È utile quando i file di origine sono template che, dopo la traduzione, devono produrre un tipo di file diverso. Ad esempio, i file POT (PO Template) sono template di origine, ma l'output tradotto dovrebbe essere costituito da file PO: ```json { "files": { "pot": { "include": ["locales/[locale]/**/*.pot"], "transformationFormat": "PO" } } } ``` Il valore deve essere una stringa che corrisponda a una delle chiavi dei formati di file supportati (ad es. `"PO"`). ### `output` Questa chiave viene usata esclusivamente per i file di General Translation, in particolare per salvare le traduzioni in locale. Se usi il CDN di GT, questa chiave non è necessaria. Il valore deve essere una stringa contenente un segnaposto `[locale]` che indica il percorso in cui verranno salvate le traduzioni. Ad esempio, se vuoi salvare le traduzioni in spagnolo in un file chiamato `ui.es.json` nella directory `public/i18n`, devi usare la seguente stringa: ```json { "output": "public/i18n/[locale].json" } ``` Questa opzione va usata solo se utilizzi `gt-next` o `gt-react` e vuoi salvare le traduzioni in locale anziché usare la CDN di GT. Al momento, può essere generato un solo file per ogni impostazione regionale. *** ### Tipo di file: `gt` [#gt] **Chiavi supportate** * `output` (obbligatorio) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "public/i18n/[locale].json" } } } ``` Questa configurazione indica allo strumento CLI di salvare le traduzioni in francese e spagnolo nella directory `public/i18n/[locale].json`. Per impostazione predefinita, con questa configurazione lo strumento CLI non pubblica le traduzioni sulla CDN di GT. *** ### Tipo di file: `json` [#json] **Chiavi supportate** * `include` (Obbligatoria) * `exclude` (Facoltativa) * `transform` (Facoltativa) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "json": { "include": ["json_files/[locale]/**/*.json"], "exclude": ["json_files/[locale]/exclude/**/*.json"] } } } ``` Supponiamo che l’impostazione regionale predefinita del tuo progetto sia `en` e che tu voglia tradurlo in `fr` e `es`. Con questa configurazione, la CLI cercherà tutti i file JSON nella sottodirectory `json_files/en/` e salverà i file tradotti in `json_files/fr/` e `json_files/es/`. Ignorerà tutti i file presenti nella sottodirectory `json_files/en/exclude/`. *** ### Tipo di file: `yaml` [#yaml] **Chiavi supportate** * `include` (Obbligatoria) * `exclude` (Facoltativa) * `transform` (Facoltativa) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "yaml": { "include": ["yaml_files/[locale]/**/*.yaml"], "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"] } } } ``` Supponiamo che l'impostazione regionale predefinita del tuo progetto sia `en` e che tu voglia tradurre il progetto in `fr` e `es`. Con questa configurazione, la CLI cercherà tutti i file YAML nella sottodirectory `yaml_files/en/` e salverà i file tradotti in `yaml_files/fr/` e `yaml_files/es/`. Ignorerà tutti i file presenti nella sottodirectory `yaml_files/en/exclude/`. *** ### Tipo di file: `mdx` [#mdx] **Chiavi supportate** * `include` (Obbligatoria) * `exclude` (Facoltativa) * `transform` (Facoltativa) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "mdx": { "include": ["content/docs/[locale]/**/*.mdx"], "transform": "*.[locale].mdx" } } } ``` Questa configurazione indica allo strumento CLI di cercare tutti i file MDX nella directory `content/docs/en` e di salvare i file tradotti nella directory `content/docs/ja`. La chiave `transform` fa sì che l'estensione dei file tradotti venga cambiata in `.ja.mdx`. *** ### Tipo di file: `md` [#md] **Chiavi supportate** * `include` (Obbligatoria) * `exclude` (Facoltativa) * `transform` (Facoltativa) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "md": { "include": ["content/docs/[locale]/**/*.md"], "exclude": ["content/docs/[locale]/exclude/**/*.md"], "transform": "*.[locale].md" } } } ``` Questa configurazione indica allo strumento CLI di cercare tutti i file MD nella directory `content/docs/en` e di salvare i file tradotti nella directory `content/docs/ja`. La chiave `transform` fa sì che l'estensione dei file tradotti venga cambiata in `.ja.md`. Tutti i file nella directory `content/docs/en/exclude` verranno ignorati. *** ### Tipo di file: `js` [#js] **Chiavi supportate** * `include` (Obbligatoria) * `exclude` (Facoltativa) * `transform` (Facoltativa) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "js": { "include": ["scripts/[locale]/**/*.js"] } } } ``` Questa configurazione indica allo strumento CLI di cercare tutti i file JavaScript nella directory `scripts/en` e di salvare i file tradotti nelle directory `scripts/fr` e `scripts/es`. *** ### Tipo di file: `ts` [#ts] **Chiavi supportate** * `include` (Obbligatoria) * `exclude` (Facoltativa) * `transform` (Facoltativa) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "ts": { "include": ["scripts/[locale]/**/*.ts"] } } } ``` Questa configurazione indica allo strumento CLI di cercare tutti i file TypeScript nella directory `scripts/en` e di salvare i file tradotti nelle directory `scripts/fr` e `scripts/es`. *** ### Tipo di file: `html` [#html] **Chiavi supportate** * `include` (Obbligatorio) * `exclude` (Facoltativo) * `transform` (Facoltativo) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "html": { "include": ["content/docs/[locale]/**/*.html"], "exclude": ["content/docs/[locale]/exclude/**/*.html"], "transform": "*.[locale].html" } } } ``` Questa configurazione farà sì che lo strumento CLI cerchi tutti i file HTML nella directory `content/docs/en` e salvi i file tradotti nella directory `content/docs/ja`. La chiave `transform` fa sì che l'estensione dei file tradotti venga modificata in `.ja.html`. Tutti i file nella directory `content/docs/en/exclude` saranno ignorati. *** ### Tipo di file: `txt` [#txt] **Chiavi supportate** * `include` (Obbligatoria) * `exclude` (Facoltativa) * `transform` (Facoltativa) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "txt": { "include": ["content/docs/[locale]/**/*.txt"], "exclude": ["content/docs/[locale]/exclude/**/*.txt"], "transform": "*.[locale].txt" } } } ``` Questa configurazione indica allo strumento CLI di cercare tutti i file di testo nella directory `content/docs/en` e di salvare i file tradotti nella directory `content/docs/ja`. La chiave `transform` fa sì che l'estensione dei file tradotti venga modificata in `.ja.txt`. Tutti i file nella directory `content/docs/en/exclude` saranno ignorati. *** ### Tipo di file: `twilioContentJson` [#twilioContentJson] **Chiavi supportate** * `include` (obbligatorio) * `exclude` (opzionale) * `transform` (opzionale) **Esempio** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "twilioContentJson": { "include": ["twilio/[locale]/**/*.json"] } } } ``` Questa configurazione farà sì che lo strumento CLI cerchi tutti i file JSON di Twilio Content nella directory `twilio/en` e salvi i file tradotti nelle directory `twilio/es` e `twilio/fr`. I file JSON di Twilio Content sono modelli strutturati utilizzati dal [Content Template Builder di Twilio](https://www.twilio.com/docs/content) per la messaggistica WhatsApp, SMS e RCS. La CLI traduce le stringhe visibili all’utente (testo del corpo, etichette dei pulsanti, titoli delle schede) preservando al contempo la struttura del modello, i segnaposto delle variabili e i campi non traducibili. *** ## Pubblicazione sulla CDN [#cdn-publishing] Per impostazione predefinita, la CLI non pubblica i file tradotti sulla CDN di GT. Se hai abilitato la CDN nelle impostazioni del progetto, puoi controllare la pubblicazione a livello globale, per singolo file o per comando. ### Flag `publish` globale Imposta `publish` al livello principale per pubblicare **tutti** i file tradotti sulla CDN: ```json title="gt.config.json" { "publish": true } ``` Puoi anche passare `--publish` ai comandi `translate`, `upload` o `save-local`: ```bash npx gt translate --publish ``` ### Flag `publish` per il JSON di GT Per pubblicare solo il formato di traduzione interno di GT, usa la chiave `publish` sotto `files.gt`: ```json title="gt.config.json" { "files": { "gt": { "output": "public/i18n/[locale].json", "publish": true } } } ``` ### Controllo della pubblicazione a livello di file Per altri tipi di file (`json`, `yaml`, `mdx`, `md`, `po`, `xliff`, `csv`, `properties`), puoi controllare la pubblicazione per singolo file usando un oggetto nell'array `include` invece di una semplice stringa glob: ```json title="gt.config.json" { "files": { "json": { "include": [ { "pattern": "locales/[locale]/*.json", "publish": true }, { "pattern": "locales/[locale]/internal/**/*.json", "publish": false } ] } } } ``` Ogni voce in `include` può essere una delle seguenti: * Una **stringa** — un pattern glob (nessuna preferenza di pubblicazione; usa l'impostazione globale `publish`) * Un **oggetto** con `pattern` (glob) e `publish` (booleano) — include o esclude esplicitamente i file corrispondenti ### Ordine di risoluzione Per un determinato file, la CLI determina se pubblicarlo nel seguente ordine: 1. **Esclusione esplicita** — il file corrisponde a una voce `include` con `"publish": false` → non viene pubblicato o viene rimosso dalla CDN 2. **Inclusione esplicita** — il file corrisponde a una voce `include` con `"publish": true` → viene pubblicato sulla CDN 3. **Fallback globale** — usa l'impostazione `publish` di primo livello (il valore predefinito è `false` se non è impostata) Se non esiste alcuna configurazione `publish` a nessun livello, il passaggio di pubblicazione viene saltato completamente. *** ## Configurazione di esempio Vediamo nel dettaglio un file `gt.config.json` di esempio: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "public/i18n/[locale].json" }, "mdx": { "include": ["content/docs/[locale]/**/*.mdx"], "transform": "*.[locale].mdx" }, "json": { "include": ["resources/[locale]/**/*.json"], "exclude": ["resources/[locale]/exclude/**/*.json"] } } } ``` In questo esempio, traduciamo i seguenti file con una singola chiamata a [`gt translate`](/docs/cli/translate): * Tutti i file MDX nella directory `content/docs/en`. * Tutti i file JSON nella directory `resources/en` (esclusi tutti i file nella directory `resources/en/exclude`). * Tutti i componenti `` inline del tuo progetto React o Next.js. * Il file `dictionary.[json|js|ts]`. GT: le traduzioni verranno salvate in `public/i18n/es.json` e `public/i18n/fr.json`. Questi file possono essere caricati con [`loadTranslations`](/docs/react/api/config/load-translations). MDX: le traduzioni verranno salvate nelle directory `content/docs/fr` e `content/docs/es`. Le estensioni dei file verranno modificate rispettivamente in `.fr.mdx` e `.es.mdx` (a partire da `.mdx`). JSON: le traduzioni verranno salvate nelle directory `resources/fr` e `resources/es`. *** ## Passaggi successivi Scopri come usare il [comando init](/docs/cli/init) per generare questo file di configurazione.