# gt: General Translation CLI tool: Configurazione URL: https://generaltranslation.com/it/docs/cli/reference/config.mdx Docs index: https://generaltranslation.com/llms.txt 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 è indietro rispetto ad alcune chiavi di file valide, tra cui `pot`, `html`, `txt`, `twilioContentJson`, `lottie`, `dotStrings`, `dotStringsdict`, `androidStrings`, `xcstrings` e `srt`, e inoltre omette `fonts` e `options.saveLocal`. Gli editor potrebbero segnalare campi dello schema non supportati finché lo schema non viene aggiornato.* ## Opzioni [#options] | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ------------------------------------ | ----------------------------------------------------------------------------- | ---------- | ----------- | ----------------------- | | [`projectId`](#project-id) | progetto usato per l'API e i workflow di traduzione. | `string` | Sì | `GT_PROJECT_ID` | | [`baseUrl`](#base-url) | URL di base per le richieste all'API di General Translation. | `string` | Sì | `https://api.gtx.dev` | | [`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ì | Specifico del framework | | [`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ì | — | | [`options.saveLocal`](#save-local) | Rileva e invia le modifiche locali alle traduzioni prima dell'enqueue. | `boolean` | Sì | `false` | ## `projectId` [#project-id] **tipo** `string` · **Facoltativo** · **predefinito** `GT_PROJECT_ID` Il progetto utilizzato per le API e per i workflow di traduzione. Il flag `--project-id` ha la precedenza sul valore della variabile d'ambiente, ma deve corrispondere a `projectId` se il config ne specifica uno. ```json title="gt.config.json" { "projectId": "project-id" } ``` ## `baseUrl` [#base-url] **tipo** `string` · **Facoltativo** · **predefinito** `https://api.gtx.dev` L'origine API utilizzata dalle richieste della CLI, incluso [`gt api`](/docs/cli/reference/commands/api). Impostalo solo se il tuo workflow utilizza un endpoint personalizzato della API di General Translation. ```json title="gt.config.json" { "baseUrl": "https://api.gtx.dev" } ``` ## `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`, `gt-react` o `gt-vue`. ```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. Gli inizializzatori dei framework che accettano un elenco di impostazioni regionali le usano anche come 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`, `gt-react-native`, `gt-tanstack-start` e `gt-vue`. | [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) | | `srt` | File di sottotitoli SubRip (`.srt`). | [SRT](/docs/cli/reference/formats/srt-files) | | `twilioContentJson` | Template Twilio Content JSON. | — | | `lottie` | File di animazione dotLottie (`.lottie`). | [Lottie](/docs/cli/reference/formats/lottie-files) | | `xcstrings` | Apple String Catalogs (`.xcstrings`). | [.xcstrings](/docs/cli/reference/formats/xcstrings-files) | | `dotStrings` | Tabelle `.strings`, una per impostazione regionale in una directory `.lproj`. | [.strings](/docs/cli/reference/formats/dot-strings-files) | | `dotStringsdict` | File di plurali `.stringsdict`, uno per impostazione regionale in una directory `.lproj`. | [.stringsdict](/docs/cli/reference/formats/dot-stringsdict-files) | | `androidStrings` | File di risorse Android `strings.xml`. | [Android strings.xml](/docs/cli/reference/formats/android-strings-files) | `dotStrings` e `dotStringsdict` richiedono `gt` 2.18.1 o versioni successive, `androidStrings` richiede `gt` 2.19.0 o versioni successive, `xcstrings` richiede `gt` 2.21.0 o versioni successive e `srt` richiede `gt` 2.22.2 o versioni successive. **Modificato nella v2.18.1:** le chiavi dei file Apple sono passate da `strings` e `stringsdict` a `dotStrings` e `dotStringsdict`. Le chiavi precedenti non sono riconosciute nelle versioni attuali. ### 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`. È obbligatorio quando un workflow di Locadex usa **Preserve local edits** senza il publishing su CDN a livello top-level; vedi [Locadex preserve local edits](#locadex-requirements). * `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 segnaposto `{...}` che vengono espansi nelle proprietà dell'impostazione regionale di destinazione. I nomi non riconosciuti restano nell'output come testo letterale. | Segnaposto | 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 segnaposto `[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. L'unica eccezione è [`androidStrings`](/docs/cli/reference/formats/android-strings-files), dove entrambi i segnaposto vengono espansi in un qualificatore di directory delle risorse Android — `fr-CA` diventa `fr-rCA` — perché Android fa fallire la build in presenza di un nome di directory `values-*` che non riesce ad analizzare. ```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 sorgente specifici del framework Un array di pattern glob per i file sorgente analizzati alla ricerca di contenuti inline. I progetti della famiglia React analizzano per impostazione predefinita i file JavaScript e TypeScript in `src`, `app`, `pages` e `components`. I progetti Vue analizzano anche i file `*.vue` nella radice, oltre ai file JavaScript, TypeScript e Vue nelle directory convenzionali di Vue e Nuxt come `composables`, `layouts`, `plugins`, `server`, `stores`, `utils` e `views`. ```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` · **facoltativo** · **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. | proprietà | Description | Type | facoltativo | 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`. Quando utilizzi un alias, imposta `defaultLocale` e le voci in `locales` sul nome dell'alias (`cn`), non sul nome canonico (`zh`). ```json title="gt.config.json" { "defaultLocale": "cn", "locales": ["cn", "fr", "en"], "customMapping": { "cn": { "code": "zh", "name": "Mandarin" } } } ``` ## `options.saveLocal` [#save-local] **tipo** `boolean` · **Facoltativo** · **predefinito** `false` Rileva le modifiche apportate ai file di traduzione locali scaricati in precedenza e ne invia le diff prima che [`gt translate`](/docs/cli/reference/commands/translate) o [`gt stage`](/docs/cli/reference/commands/stage) accodino nuove operazioni. Impostalo nell'oggetto `options` di primo livello. I flag `--save-local` e `--no-save-local` hanno la precedenza su questa impostazione per una singola esecuzione. ```json title="gt.config.json" { "options": { "saveLocal": true } } ``` ### Cronologia delle versioni | Versione | Modifiche | | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `2.20.3` | Le modifiche locali sono diventate opt-in; imposta questa chiave su `true` oppure passa `--save-local` per abilitare lo step. | ## pubblicazione su 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. ## Locadex preserve local edits [#locadex-requirements] Quando un'automation Locadex ha l'opzione **Preserve local edits** attiva, configura `"publish": true` a livello top-level oppure `files.gt.output`. Locadex verifica questa condizione prima di avviare la traduzione. ```json title="gt.config.json" { "files": { "gt": { "output": "public/i18n/[locale].json" } } } ``` Le impostazioni per singolo file e `files.gt.publish` non soddisfano questo requisito. Senza il publishing su CDN a livello top-level, `files.gt.output` indica al workflow dove sono archiviate le traduzioni GTJSON locali, così da poter preservare le modifiche. ## 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`. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.