Panoramica

Il file gt.config.json serve a configurare le impostazioni di GT del tuo progetto. Va collocato nella directory radice del progetto.

La procedura guidata della CLI npx gtx-cli init genererà automaticamente un file gt.config.json nel tuo progetto.

Configurazione

Il file gt.config.json accetta le seguenti proprietà, ma non si limita a queste:

• defaultLocale: La lingua/locale predefinita del tuo progetto. È quella in cui è scritto il contenuto sorgente. È anche la lingua/locale di fallback del progetto (se usi gt-next o gt-react).

• locales: Un array di lingue/locali per il tuo progetto. Sono le lingue/locali in cui vuoi tradurre il progetto. Vedi le lingue/locali supportate per ulteriori informazioni. Se stai usando gt-next o gt-react, sono anche le lingue/locali supportate dalla tua app.

• files: Oggetto che contiene informazioni sul contenuto da tradurre.

• stageTranslations: Flag booleano opzionale che indica se il progetto è configurato per la revisione umana.

• src: Array opzionale di pattern glob per i file sorgente. Per impostazione predefinita è impostato su:

[
  "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.

{
  "$schema": "https://assets.gtx.dev/config-schema.json",
}

Ecco un modello del file 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 locale

Se vuoi creare un alias per una locale (ad es. cn invece di zh), puoi specificare una mappatura personalizzata nel file gt.config.json.

{
  "customMapping": {
    "cn": {
      "code": "zh"
    }
  }
}

Puoi anche specificare attributi diversi per la locale alias.

{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Mandarino",
    }
  }
}

files

Tipi di file supportati

files deve contenere una chiave per ogni tipo di file che vuoi tradurre. Puoi configurare il progetto per combinare diversi tipi di file e tradurli tutti. Al momento supportiamo i seguenti tipi di file:

• gt: file di General Translation.
• json: file JSON.
• yaml: file YAML.
• mdx: file di componenti Markdown (MDX).
• md: file Markdown (MD).
• js: file JavaScript.
• ts: file TypeScript.

Ogni tipo di file deve corrispondere a un oggetto che contiene una o più delle seguenti chiavi:

• include
• exclude
• transform
• output

include

Se utilizzata, la chiave include deve contenere un array di pattern glob che corrispondono ai file da tradurre.

Devi usare il segnaposto [locale] nei pattern glob per garantire che i file sorgente vengano individuati correttamente e che i file tradotti vengano salvati nella posizione corretta. Lo strumento CLI sostituirà il segnaposto [locale] con il valore di defaultLocale quando cerca i file traducibili.

Lo strumento CLI salverà i file tradotti nel percorso corrispondente, sostituendo il segnaposto [locale] con il codice della locale di destinazione.

{
  "include": ["docs/[locale]/**/*.json"]
}

exclude

Se utilizzata, la chiave exclude deve avere come valore un array di pattern glob che corrispondano ai file da escludere dalla traduzione.

Il pattern è lo stesso di include, con la differenza che il segnaposto [locale] è facoltativo. Se presente, verrà sostituito con il valore di defaultLocale.

{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}

Se vuoi escludere file dalla traduzione per tutte le lingue, puoi usare il segnaposto [locales] al posto di [locale].

{
  "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 il carattere jolly *, che verrà sostituito con il nome del file originale (tutto ciò che precede il primo .).

Ad esempio, se vuoi che l’estensione di tutti i file tradotti sia .[locale].json invece di .json, puoi usare la seguente configurazione:

{
  "transform": "*.[locale].json"
}

In alternativa, se transform è un oggetto, deve contenere le seguenti proprietà:

• match (opzionale): Pattern regex per individuare le stringhe; supporta gruppi di cattura
• replace (obbligatorio): Stringa o pattern regex con cui sostituire la corrispondenza

Entrambi i valori supportano i gruppi di cattura regex e vengono applicati al nome file relativo completo del file di output.

{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}

Ad esempio, la configurazione sopra farà sì che i file tradotti vengano salvati in una sottodirectory della lingua di destinazione.

Segnaposto speciali

L'opzione transform supporta diversi segnaposto speciali utilizzabili sia nelle stringhe match che replace:

• {locale}: il segnaposto del codice locale che si comporta in modo diverso a seconda del contesto:
  • Nelle stringhe match: sostituito con il codice locale predefinito (ad es. "en") per aiutare a identificare i file sorgente
  • Nelle stringhe replace: sostituito con il codice locale di destinazione (ad es. "fr", "es") per i file di output tradotti

Ad esempio, se il locale predefinito è "en" e stai traducendo in "fr":

• Un pattern di match "content/{locale}/file.md" diventa "content/en/file.md"
• Un pattern di replace "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.

output

Questa chiave è utilizzata esclusivamente per i file di General Translation, nello specifico per salvare le traduzioni in locale. Se utilizzi 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.

Per esempio, se vuoi salvare le traduzioni in spagnolo in un file chiamato ui.es.json nella directory public/i18n, usa la seguente stringa:

{
  "output": "public/i18n/[locale].json"
}

Tipo di file: gt

Chiavi supportate

• output (obbligatoria)

Esempio

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
  }
}

Questa configurazione farà sì che lo strumento CLI salvi le traduzioni in francese e in spagnolo nella directory public/i18n/[locale].json.

Per impostazione predefinita, con questa configurazione lo strumento CLI non pubblicherà le traduzioni sul CDN di GT.

Tipo di file: json

Chiavi supportate

• include (Obbligatorio)
• exclude (Opzionale)
• transform (Opzionale)

Esempio

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}

Poniamo che la locale 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 JSON nella sottodirectory json_files/en/ e salverà i file tradotti in json_files/fr/ e json_files/es/.

Ignorerà qualsiasi file nella sottodirectory json_files/en/exclude/.

Tipo di file: yaml

Chiavi supportate

• include (Obbligatorio)
• exclude (Facoltativo)
• transform (Facoltativo)

Esempio

{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}

Supponiamo che la locale predefinita del tuo progetto sia en e che tu voglia tradurlo 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à qualsiasi file nella sottodirectory yaml_files/en/exclude/.

Tipo di file: mdx

Chiavi supportate

• include (Obbligatoria)
• exclude (Opzionale)
• transform (Opzionale)

Esempio

{
  "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 in modo che l’estensione dei file tradotti venga cambiata in .ja.mdx.

Tipo di file: md

Chiavi supportate

• include (Obbligatoria)
• exclude (Opzionale)
• transform (Opzionale)

Esempio

{
  "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 modificata in .ja.md.

Tutti i file nella directory content/docs/en/exclude verranno ignorati.

Tipo di file: js

Chiavi supportate

• include (Obbligatorio)
• exclude (Facoltativo)
• transform (Facoltativo)

Esempio

{
  "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.

La chiave transform fa in modo che l’estensione dei file tradotti venga modificata in .fr.js e .es.js rispettivamente (da .js).

Tipo di file: ts

Chiavi supportate

• include (Obbligatorio)
• exclude (Opzionale)
• transform (Opzionale)

Esempio

{ 
  "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.

La chiave transform fa sì che l’estensione dei file tradotti venga modificata in .fr.ts e .es.ts, rispettivamente (a partire da .ts).

Configurazione di esempio

Analizziamo un file gt.config.json come esempio:

{
  "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 esecuzione di gtx-cli translate:

• Tutti i file MDX nella directory content/docs/en.
• Tutti i file JSON nella directory resources/en (escludendo i file nella directory resources/en/exclude).
• Tutti i componenti <T> in linea nel 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.

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 (da .mdx).

JSON: Le traduzioni verranno salvate nelle directory resources/fr e resources/es.

Prossimi passaggi

Scopri come utilizzare il comando init per generare questo file di configurazione.