# gt: General Translation CLI tool: Configurazione URL: https://generaltranslation.com/it/docs/cli/reference/config.mdx --- title: Configurazione description: Configura la CLI di General Translation con il file gt.config.json. Riferimento API per gt.config.json. --- Il file `gt.config.json` definisce cosa traduce la CLI e dove vengono salvati i risultati. Inseriscilo nella directory radice del progetto. Puoi crearlo con [`gt init`](/docs/cli/reference/commands/init) o [`gt configure`](/docs/cli/reference/commands/configure), oppure scriverlo manualmente. *Nota: aggiungi il [JSON Schema](https://assets.gtx.dev/config-schema.json) con una chiave `$schema` per la validazione nell'editor e il completamento automatico. Lo schema pubblicato non include ancora le chiavi `lottie` e `fonts` aggiunte in `gt` 2.16.0, quindi gli editor potrebbero segnalare tali impostazioni valide finché lo schema non viene aggiornato.* ## Opzioni [#options] | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ------------------------------------ | ----------------------------------------------------------------------------- | ---------- | ----------- | ------------------ | | [`defaultLocale`](#default-locale) | Impostazione regionale in cui è scritto il contenuto sorgente. | `string` | Sì | `en` | | [`locales`](#locales) | Impostazioni regionali di destinazione in cui tradurre. | `string[]` | Sì | — | | [`files`](#files) | Quali file tradurre e dove salvarli. | `object` | Sì | — | | [`fonts`](#fonts) | File di font da rendere disponibili per i job di traduzione Lottie. | `object` | Sì | — | | [`publish`](#publish) | Pubblica i file tradotti sulla CDN. | `boolean` | Sì | `false` | | [`stageTranslations`](#stage) | Usa il workflow di staging prima di scaricare le traduzioni. | `boolean` | Sì | `false` | | [`requiresReview`](#requires-review) | Criterio predefinito di revisione per tutti i file tradotti. | `boolean` | Sì | `false` | | [`src`](#src) | Pattern glob per i file sorgente analizzati alla ricerca di contenuto inline. | `string[]` | Sì | Vedi [`src`](#src) | | [`dictionary`](#dictionary) | Percorso di un file dizionario. | `string` | Sì | — | | [`branchOptions`](#branch-options) | Impostazioni per il tracciamento delle traduzioni per branch. | `object` | Sì | — | | [`customMapping`](#custom-mapping) | Alias delle impostazioni regionali e override delle proprietà. | `object` | Sì | — | ## `defaultLocale` [#default-locale] **Tipo** `string` · **Facoltativo** · **Predefinito** `en` L'impostazione regionale in cui sono scritti i contenuti sorgente. È l'impostazione regionale da cui la CLI traduce e quella di fallback quando usi `gt-next` o `gt-react`. ```json title="gt.config.json" { "defaultLocale": "en" } ``` ## `locales` [#locales] **Tipo** `string[]` · **Facoltativo** · **Predefinito** — Le impostazioni regionali di destinazione in cui tradurre il contenuto. Consulta [impostazioni regionali supportate](/docs/platform/dashboard/reference/supported-locales) per i codici accettati. Quando usi `gt-next` o `gt-react`, queste sono anche le impostazioni regionali supportate dalla tua app. ```json title="gt.config.json" { "locales": ["fr", "es", "ja"] } ``` ## `files` [#files] **Tipo** `object` · **Facoltativo** · **Predefinito** — Un oggetto con una chiave per ogni tipo di file da tradurre. A ogni tipo corrisponde un oggetto di impostazioni. Consulta [Formati di file](/docs/cli/reference/formats/gt-jsx-files) per indicazioni specifiche per ciascun tipo. ### Tipi di file supportati | Chiave | Tipo di file | Riferimento | | ------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- | | `gt` | File General Translation per `gt-next`, `gt-react` e `gt-react-native`. | [GT](/docs/cli/reference/formats/gt-jsx-files) | | `json` | File JSON. | [JSON](/docs/cli/reference/formats/json-files) | | `yaml` | File YAML (`.yaml` e `.yml`). | [YAML](/docs/cli/reference/formats/yaml-files) | | `pot` | File gettext PO/POT. | [PO / POT](/docs/cli/reference/formats/po-pot-files) | | `mdx` | File MDX. | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files) | | `md` | File Markdown. | [MDX and Markdown](/docs/cli/reference/formats/mdx-md-files) | | `ts` | File TypeScript. | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files) | | `js` | File JavaScript. | [TypeScript and JavaScript](/docs/cli/reference/formats/ts-js-files) | | `html` | File HTML. | [HTML](/docs/cli/reference/formats/html-files) | | `txt` | File di testo semplice. | [Plain text](/docs/cli/reference/formats/plain-text-files) | | `twilioContentJson` | Template Twilio Content JSON. | — | | `lottie` | File di animazione dotLottie (`.lottie`). | [Lottie](/docs/cli/reference/formats/lottie-files) | ### Chiavi del tipo di file Ogni tipo di file accetta le seguenti chiavi. * `include` — un array di pattern glob che corrispondono ai file da tradurre. Usa il segnaposto `[locale]`: la CLI lo sostituisce con `defaultLocale` per trovare i file sorgente e con ciascun codice di destinazione per salvare le traduzioni. Obbligatorio per tutti i tipi tranne `gt`. * `exclude` — un array di pattern glob da escludere. Il segnaposto `[locale]` qui è facoltativo; usa `[locales]` per escludere un percorso in tutte le impostazioni regionali. * `transform` — rimappa i nomi dei file di output. Una stringa con il carattere jolly `*` rimappa l'estensione (ad esempio `*.[locale].json`). Un oggetto con `match` e `replace` supporta i gruppi di cattura regex e i segnaposto dell'impostazione regionale in [segnaposto delle impostazioni regionali](#locale-placeholders). * `transformationFormat` — genera file tradotti in un formato diverso da quello sorgente. Ad esempio, i file sorgente `pot` con `"transformationFormat": "PO"` producono file `.po`. * `requiresReview` — rende disponibili i file tradotti solo dopo la revisione umana. Accetta `true`/`false` oppure un oggetto con array glob `include` e `exclude`, in cui `exclude` ha la precedenza. * `output` — solo per i file `gt`, il percorso di salvataggio locale con un segnaposto `[locale]`, ad esempio `public/i18n/[locale].json`. * `parsingFlags` — solo per i file `gt`, flag che controllano il parsing del contenuto inline. Vedi [`autoderive`](/docs/cli/guides/using-autoderive) e [automatic JSX injection](/docs/cli/guides/using-auto-jsx). ```json title="gt.config.json" { "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"] } } } ``` ### segnaposto delle impostazioni regionali [#locale-placeholders] Il valore `replace` di un oggetto `transform` accetta placeholder `{...}` che vengono espansi nelle proprietà dell'impostazione regionale di destinazione. I nomi non riconosciuti restano nell'output come testo letterale. | Placeholder | Descrizione | Esempio per `pt-BR` | | -------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------- | | `{locale}` | L'impostazione regionale esattamente come indicata in [`locales`](#locales). `{localeCode}` è un alias. | `pt-BR` | | `{localeName}` | Nome inglese dell'impostazione regionale, inclusa la regione. | `Brazilian Portuguese` | | `{localeNativeName}` | Nome nativo dell'impostazione regionale, inclusa la regione. | `português (Brasil)` | | `{languageCode}` | Solo il sottotag della lingua. | `pt` | | `{regionCode}` | Solo il sottotag della regione. | `BR` | | `{scriptCode}` | Solo il sottotag della scrittura. | `Latn` | | `{minimizedCode}` | Forma non ambigua più breve del tag. | `pt` | | `{maximizedCode}` | Tag completamente espanso, inclusa la scrittura. | `pt-Latn-BR` | | `{emoji}` | Emoji della bandiera associata all'impostazione regionale. | 🇧🇷 | Sono accettati anche per nome gli altri campi di [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties), inclusi `languageName`, `nativeLanguageName`, `regionName`, `nativeRegionName`, `scriptName`, `nativeScriptName`, `nameWithRegionCode`, `nativeNameWithRegionCode`, `maximizedName`, `nativeMaximizedName`, `minimizedName` e `nativeMinimizedName`. `{locale}` usa la grafia della configurazione anziché la forma canonica BCP-47; pertanto, un'impostazione regionale configurata come `fr-ca` produce `fr-ca` e non `fr-CA`. Questo comportamento corrisponde al placeholder `[locale]` in `include`, `exclude` e `output`, garantendo la coerenza tra percorsi dei file e URL localizzati. Usa invece `{minimizedCode}`, `{maximizedCode}` o `{regionCode}` quando ti serve un tag normalizzato. ```json title="gt.config.json" { "files": { "json": { "include": ["locales/[locale]/**/*.json"], "transform": { "match": "locales/(.*)/(.*)\\.json", "replace": "locales/{locale}/$2.{languageCode}.json" } } } } ``` ## `fonts` [#fonts] **Tipo** `object` · **Facoltativo** · **Predefinito** — File di font da caricare prima dell'avvio dei job di traduzione. Usa i pattern glob `include` e l'eventuale `exclude`, risolti a partire dalla radice del progetto. Corrisponde ai file `.ttf` e `.otf`; la CLI li legge come dati binari e li carica come risorse persistenti dell'Organization per l'elaborazione del layout Lottie. | Proprietà | Descrizione | Tipo | Facoltativo | Predefinito | | --------- | ----------------------------------------------- | ---------- | ----------- | ----------- | | `include` | Pattern glob dei font da caricare. | `string[]` | No | — | | `exclude` | Pattern glob da escludere dalle corrispondenze. | `string[]` | Sì | `[]` | ```json title="gt.config.json" { "fonts": { "include": ["public/fonts/**/*.{ttf,otf}"], "exclude": ["public/fonts/legacy/**"] } } ``` La CLI sincronizza i font corrispondenti prima di eseguire [`gt stage`](/docs/cli/reference/commands/stage), [`gt upload`](/docs/cli/reference/commands/upload), [`gt enqueue`](/docs/cli/reference/commands/enqueue) e [`gt translate`](/docs/cli/reference/commands/translate), quando questi comandi accodano nuovo lavoro. Quando `stageTranslations` è abilitato, [`gt translate`](/docs/cli/reference/commands/translate) scarica solo la versione preparata e non sincronizza i font. Se la sincronizzazione dei font non riesce, viene generato un avviso, ma la traduzione non viene interrotta; l'elaborazione Lottie continua con font di fallback. Per informazioni sulla convalida e sull'archiviazione dei font, consulta [Carica le risorse del progetto](/docs/platform/openapi/reference/project/upload-assets). ## `publish` [#publish] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `false` Quando è `true`, i file tradotti vengono pubblicati sulla CDN di General Translation dopo [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload) o [`save-local`](/docs/cli/reference/commands/save-local). Le traduzioni Lottie restano disponibili solo tramite API e download della CLI; impostare `publish` non rende disponibili i file `.lottie` dalla CDN. Vedi [la pubblicazione sulla CDN](#cdn-publishing) per il controllo a livello di file e di comando. ```json title="gt.config.json" { "publish": true } ``` ## `stageTranslations` [#stage] **Type** `boolean` · **facoltativo** · **Default** `false` Quando è `true`, la CLI scarica solo le versioni inviate con [`gt stage`](/docs/cli/reference/commands/stage). La CLI lo imposta automaticamente la prima volta che esegui [`gt stage`](/docs/cli/reference/commands/stage). Utilizza il workflow di staging per la revisione umana e per formati asincroni come [Lottie](/docs/cli/reference/formats/lottie-files); le impostazioni di revisione del progetto determinano se anche le traduzioni completate richiedono approvazione. ## `requiresReview` [#requires-review] **Tipo** `boolean` · **Opzionale** · **Predefinito** `false` L'impostazione predefinita a livello di progetto per il blocco della revisione: quando è `true`, gli artefatti tradotti richiedono l'approvazione prima che il client li utilizzi. Deve essere un valore booleano — usa la chiave per file [`files..requiresReview`](#files) (che accetta un valore booleano o glob `{ include, exclude }`) per gli override con ambito glob. Una policy per file ha la precedenza; i file che non corrispondono né a un glob `include` né a un glob `exclude` ricorrono a questa impostazione predefinita di livello superiore. ```json title="gt.config.json" { "requiresReview": true } ``` ## `src` [#src] **Tipo** `string[]` · **Facoltativo** · **Predefinito** glob `src`, `app`, `pages`, `components` Un array di pattern glob per i file sorgente analizzati alla ricerca di contenuti inline quando usi `gt-next`, `gt-react` o `gt-react-native`. ```json title="gt.config.json" { "src": [ "src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}", "components/**/*.{js,jsx,ts,tsx}" ] } ``` ## `dictionary` [#dictionary] **Tipo** `string` · **Opzionale** · **Predefinito** — Il percorso relativo di un file di dizionario. Se omesso, la CLI cerca `dictionary.[json|ts|js]` in `./src` e `./`. ```json title="gt.config.json" { "dictionary": "./dictionary.json" } ``` ## `branchOptions` [#branch-options] **Type** `object` · **Optional** · **Default** — Configura il tracciamento delle traduzioni basato sui branch. Vedi [Tracciamento delle traduzioni per branch](/docs/cli/guides/branching). I flag della CLI hanno la precedenza su questi valori. | Property | Description | Type | Optional | Default | | -------------------- | --------------------------------------------------------------------------- | --------- | -------- | -------- | | `enabled` | Abilita il branching per il progetto. | `boolean` | Yes | `false` | | `currentBranch` | Sovrascrive il nome del branch rilevato. | `string` | Yes | — | | `autoDetectBranches` | Rileva le relazioni tra i branch in ingresso e quelli attualmente estratti. | `boolean` | Yes | `true` | | `remoteName` | Remote Git usato per il rilevamento dei branch. | `string` | Yes | `origin` | ```json title="gt.config.json" { "branchOptions": { "enabled": true, "currentBranch": "my-feature-branch", "autoDetectBranches": true, "remoteName": "origin" } } ``` ## `customMapping` [#custom-mapping] **Tipo** `object` · **Facoltativo** · **Predefinito** — Consente di assegnare a un'impostazione regionale un alias con un codice diverso e, facoltativamente, di sovrascriverne le proprietà. Ad esempio, assegna l'alias `cn` al codice ufficiale `zh`. ```json title="gt.config.json" { "customMapping": { "cn": { "code": "zh", "name": "Mandarin" } } } ``` ## Pubblicazione sul CDN [#cdn-publishing] Per impostazione predefinita, la CLI non pubblica sul CDN. Quando il CDN è abilitato nelle impostazioni del progetto, puoi controllare la pubblicazione a livello globale, per singolo file o per comando. * **Globale:** imposta [`publish`](#publish) di primo livello su `true`, oppure passa `--publish` a [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload) o [`save-local`](/docs/cli/reference/commands/save-local). * **Solo file GT:** imposta `publish: true` sotto `files.gt`. * **Per file:** in un array `include`, sostituisci una stringa glob con un oggetto con `pattern` e `publish` per includere o escludere i file corrispondenti. ```json title="gt.config.json" { "files": { "json": { "include": [ { "pattern": "locales/[locale]/*.json", "publish": true }, { "pattern": "locales/[locale]/internal/**/*.json", "publish": false } ] } } } ``` Per qualsiasi file, la CLI determina la pubblicazione in questo ordine: un opt-out esplicito con `"publish": false`, poi un opt-in esplicito con `"publish": true`, poi l'impostazione globale `publish`. Se non esiste alcuna configurazione di pubblicazione a nessun livello, il passaggio di pubblicazione viene ignorato. ## Configurazione di esempio [#example] ```json title="gt.config.json" { "$schema": "https://assets.gtx.dev/config-schema.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"] } } } ``` Con una singola chiamata a [`gt translate`](/docs/cli/reference/commands/translate) con questa configurazione, vengono tradotti i file MDX in `content/docs/en` (salvati in `content/docs/fr` e `content/docs/es` come `.fr.mdx` e `.es.mdx`), i file JSON in `resources/en` (escluso `resources/en/exclude`) e tutti i componenti [``](/docs/react/reference/components/t) inline e le voci del dizionario. Le traduzioni di GT vengono salvate in `public/i18n/fr.json` e `public/i18n/es.json`.