# gt: General Translation CLI tool: Configuración
URL: https://generaltranslation.com/es/docs/cli/reference/config.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Configura la CLI de General Translation con el archivo gt.config.json. Referencia de la API de gt.config.json.
El archivo `gt.config.json` define qué traduce la CLI y dónde se guardan los resultados. Colócalo en la raíz de tu proyecto. Créalo con [`gt init`](/docs/cli/reference/commands/init) o [`gt configure`](/docs/cli/reference/commands/configure), o escríbelo manualmente.
*Nota: Añade el [JSON Schema](https://assets.gtx.dev/config-schema.json) con una clave `$schema` para la validación y el autocompletado en el editor. El esquema publicado va por detrás de algunas claves de archivo válidas, como `pot`, `html`, `txt`, `twilioContentJson`, `lottie`, `dotStrings`, `dotStringsdict`, `androidStrings`, `xcstrings` y `srt`, y además omite `fonts` y `options.saveLocal`. Los editores podrían marcar campos no admitidos por el esquema hasta que este se actualice.*
## Opciones [#options]
| Opción | Descripción | Tipo | Opcional | Predeterminado |
| ------------------------------------ | ----------------------------------------------------------------------------------- | ---------- | -------- | --------------------- |
| [`projectId`](#project-id) | project usado para la API y los flujos de trabajo de traducción. | `string` | Sí | `GT_PROJECT_ID` |
| [`baseUrl`](#base-url) | URL base para las solicitudes a la General Translation API. | `string` | Sí | `https://api.gtx.dev` |
| [`defaultLocale`](#default-locale) | Configuración regional en la que está escrito el contenido de origen. | `string` | Sí | `en` |
| [`locales`](#locales) | Configuraciones regionales de destino a las que traducir. | `string[]` | Sí | — |
| [`files`](#files) | Qué archivos traducir y dónde guardarlos. | `object` | Sí | — |
| [`fonts`](#fonts) | Archivos de fuentes disponibles para los trabajos de traducción de Lottie. | `object` | Sí | — |
| [`publish`](#publish) | Publicar los archivos traducidos en la CDN. | `boolean` | Sí | `false` |
| [`stageTranslations`](#stage) | Usar el flujo de trabajo de preparación antes de descargar las traducciones. | `boolean` | Sí | `false` |
| [`requiresReview`](#requires-review) | Política predeterminada de revisión obligatoria para todos los archivos traducidos. | `boolean` | Sí | `false` |
| [`src`](#src) | Patrones glob de archivos fuente que se analizan en busca de contenido inline. | `string[]` | Sí | Según el framework |
| [`dictionary`](#dictionary) | Ruta a un archivo de diccionario. | `string` | Sí | — |
| [`branchOptions`](#branch-options) | Configuración para el seguimiento de traducciones por rama. | `object` | Sí | — |
| [`customMapping`](#custom-mapping) | Alias de configuración regional y sobrescrituras de propiedades. | `object` | Sí | — |
| [`options.saveLocal`](#save-local) | Detectar y enviar los cambios de traducción locales antes de encolarlos. | `boolean` | Sí | `false` |
## `projectId` [#project-id]
**tipo** `string` · **opcional** · **predeterminado** `GT_PROJECT_ID`
El proyecto que se usa para la API y los flujos de trabajo de traducción. La opción `--project-id` reemplaza el valor del entorno, pero debe coincidir con `projectId` cuando la configuración lo incluye.
```json title="gt.config.json"
{
"projectId": "project-id"
}
```
## `baseUrl` [#base-url]
**Type** `string` · **Optional** · **predeterminado** `https://api.gtx.dev`
El origen de la API que utilizan las solicitudes del CLI, incluido [`gt api`](/docs/cli/reference/commands/api). Configúralo solo cuando tu flujo de trabajo use un endpoint personalizado de la General Translation API.
```json title="gt.config.json"
{
"baseUrl": "https://api.gtx.dev"
}
```
## `defaultLocale` [#default-locale]
**Tipo** `string` · **Opcional** · **Predeterminado** `en`
La configuración regional en la que está escrito tu contenido de origen. Esta es la configuración regional desde la que traduce la CLI y la configuración regional de respaldo cuando usas `gt-next`, `gt-react` o `gt-vue`.
```json title="gt.config.json"
{
"defaultLocale": "en"
}
```
## `locales` [#locales]
**Tipo** `string[]` · **Opcional** · **Predeterminado** —
Las configuraciones regionales de destino a las que se traducirá. Consulta [configuraciones regionales compatibles](/docs/platform/dashboard/reference/supported-locales) para ver los códigos aceptados. Los inicializadores de framework que aceptan una lista de configuraciones regionales también las usan como las configuraciones regionales que admite tu aplicación.
```json title="gt.config.json"
{
"locales": ["fr", "es", "ja"]
}
```
## `files` [#files]
**Tipo** `object` · **Opcional** · **Predeterminado** —
Un objeto con una clave por cada tipo de archivo que se traduzca. Cada tipo corresponde a un objeto de configuración. Consulta [Formatos de archivo](/docs/cli/reference/formats/gt-jsx-files) para ver la guía específica de cada tipo.
### Tipos de archivo admitidos
| Clave | Tipo de archivo | Referencia |
| ------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `gt` | Archivos de General Translation para `gt-next`, `gt-react`, `gt-react-native`, `gt-tanstack-start` y `gt-vue`. | [GT](/docs/cli/reference/formats/gt-jsx-files) |
| `json` | Archivos JSON. | [JSON](/docs/cli/reference/formats/json-files) |
| `yaml` | Archivos YAML (`.yaml` y `.yml`). | [YAML](/docs/cli/reference/formats/yaml-files) |
| `pot` | Archivos gettext PO/POT. | [PO / POT](/docs/cli/reference/formats/po-pot-files) |
| `mdx` | Archivos MDX. | [MDX y Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `md` | Archivos Markdown. | [MDX y Markdown](/docs/cli/reference/formats/mdx-md-files) |
| `ts` | Archivos TypeScript. | [TypeScript y JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `js` | Archivos JavaScript. | [TypeScript y JavaScript](/docs/cli/reference/formats/ts-js-files) |
| `html` | Archivos HTML. | [HTML](/docs/cli/reference/formats/html-files) |
| `txt` | Archivos de texto sin formato. | [Texto sin formato](/docs/cli/reference/formats/plain-text-files) |
| `srt` | Archivos de subtítulos SubRip (`.srt`). | [SRT](/docs/cli/reference/formats/srt-files) |
| `twilioContentJson` | Plantillas de Twilio Content JSON. | — |
| `lottie` | Archivos de animación dotLottie (`.lottie`). | [Lottie](/docs/cli/reference/formats/lottie-files) |
| `xcstrings` | Catálogos de cadenas de Apple (`.xcstrings`). | [.xcstrings](/docs/cli/reference/formats/xcstrings-files) |
| `dotStrings` | Tablas `.strings`, una por configuración regional en un directorio `.lproj`. | [.strings](/docs/cli/reference/formats/dot-strings-files) |
| `dotStringsdict` | Archivos de plurales `.stringsdict`, uno por configuración regional en un directorio `.lproj`. | [.stringsdict](/docs/cli/reference/formats/dot-stringsdict-files) |
| `androidStrings` | Archivos de recursos `strings.xml` de Android. | [Android strings.xml](/docs/cli/reference/formats/android-strings-files) |
`dotStrings` y `dotStringsdict` requieren `gt` 2.18.1 o posterior, `androidStrings` requiere `gt` 2.19.0 o posterior, `xcstrings` requiere `gt` 2.21.0 o posterior y `srt` requiere `gt` 2.22.2 o posterior.
**Cambio en la v2.18.1:** Las claves de los archivos de Apple pasaron de `strings` y `stringsdict` a `dotStrings` y `dotStringsdict`. Las claves anteriores no se reconocen en las versiones actuales.
### Claves por tipo de archivo
Cada tipo de archivo acepta las siguientes claves.
* `include` — una lista de patrones glob que coinciden con los archivos que se van a traducir. Usa el marcador de posición `[locale]`: la CLI lo reemplaza por `defaultLocale` para encontrar los archivos fuente y por cada código de destino para guardar las traducciones. Obligatorio para todos los tipos excepto `gt`.
* `exclude` — una lista de patrones glob que se omiten. El marcador de posición `[locale]` es opcional aquí; usa `[locales]` para excluir una ruta en todas las configuraciones regionales.
* `transform` — reasigna los nombres de los archivos de salida. Una cadena con el comodín `*` reasigna la extensión (por ejemplo, `*.[locale].json`). Un objeto con `match` y `replace` admite grupos de captura regex y los marcadores de posición de configuración regional en [Marcadores de posición de configuración regional](#locale-placeholders).
* `transformationFormat` — genera archivos traducidos en un formato distinto del archivo fuente. Por ejemplo, los archivos fuente `pot` con `"transformationFormat": "PO"` producen archivos `.po`.
* `requiresReview` — hace que los archivos traducidos requieran revisión humana. Acepta `true`/`false` o un objeto con listas glob `include` y `exclude`, donde `exclude` tiene prioridad.
* `output` — solo para archivos `gt`, la ruta de guardado local con un marcador de posición `[locale]`, como `public/i18n/[locale].json`. Es obligatorio cuando un workflow de Locadex usa **Preserve local edits** sin publicación en el CDN de nivel superior; consulta [Preserve local edits de Locadex](#locadex-requirements).
* `parsingFlags` — solo para archivos `gt`, flags que controlan el análisis del contenido inline. Consulta [`autoderive`](/docs/cli/guides/using-autoderive) e [inyección automática de JSX](/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"]
}
}
}
```
### Marcadores de posición de la configuración regional [#locale-placeholders]
El valor `replace` de un objeto `transform` acepta marcadores de posición `{...}` que se expanden en propiedades de la configuración regional de destino. Los nombres no reconocidos se conservan en la salida como texto literal.
| Marcador de posición | Descripción | Ejemplo para `pt-BR` |
| -------------------- | ------------------------------------------------------------------------------------------------ | ---------------------- |
| `{locale}` | La configuración regional tal como aparece en [`locales`](#locales). `{localeCode}` es un alias. | `pt-BR` |
| `{localeName}` | Nombre de la configuración regional en inglés, incluida la región. | `Brazilian Portuguese` |
| `{localeNativeName}` | Nombre nativo de la configuración regional, incluida la región. | `português (Brasil)` |
| `{languageCode}` | Subetiqueta de idioma por sí sola. | `pt` |
| `{regionCode}` | Subetiqueta de región por sí sola. | `BR` |
| `{scriptCode}` | Subetiqueta de escritura por sí sola. | `Latn` |
| `{minimizedCode}` | Forma inequívoca más corta de la etiqueta. | `pt` |
| `{maximizedCode}` | Etiqueta completamente expandida, incluida la escritura. | `pt-Latn-BR` |
| `{emoji}` | Emoji de bandera asociado a la configuración regional. | 🇧🇷 |
Los demás campos de [`LocaleProperties`](/docs/platform/core/reference/types/locale-properties) también se aceptan por nombre, incluidos `languageName`, `nativeLanguageName`, `regionName`, `nativeRegionName`, `scriptName`, `nativeScriptName`, `nameWithRegionCode`, `nativeNameWithRegionCode`, `maximizedName`, `nativeMaximizedName`, `minimizedName` y `nativeMinimizedName`.
`{locale}` usa la grafía de tu configuración en lugar de la forma canónica BCP-47; por tanto, una configuración regional definida como `fr-ca` genera `fr-ca` y no `fr-CA`. Esto coincide con el marcador de posición `[locale]` en `include`, `exclude` y `output`, de modo que las rutas de archivo y las URL localizadas sean coherentes. Usa `{minimizedCode}`, `{maximizedCode}` o `{regionCode}` cuando necesites una etiqueta normalizada.
La única excepción es [`androidStrings`](/docs/cli/reference/formats/android-strings-files), donde ambos marcadores de posición se expanden a un calificador de directorio de recursos de Android — `fr-CA` se convierte en `fr-rCA` — porque Android hace fallar la compilación si encuentra un nombre de directorio `values-*` que no puede analizar.
```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` · **Opcional** · **Predeterminado** —
Archivos de fuentes que se cargan antes de ejecutar los trabajos de traducción. Usa los patrones glob `include` y el opcional `exclude`, que se resuelven desde la raíz del proyecto. Incluye archivos `.ttf` y `.otf`; la CLI los lee como datos binarios y los carga como recursos persistentes de Organization para el procesamiento de diseño de Lottie.
| Propiedad | Descripción | Tipo | Opcional | Predeterminado |
| --------- | ---------------------------------------------------- | ---------- | -------- | -------------- |
| `include` | Patrones glob de fuentes que se cargarán. | `string[]` | No | — |
| `exclude` | Patrones glob que se excluirán de las coincidencias. | `string[]` | Sí | `[]` |
```json title="gt.config.json"
{
"fonts": {
"include": ["public/fonts/**/*.{ttf,otf}"],
"exclude": ["public/fonts/legacy/**"]
}
}
```
La CLI sincroniza las fuentes correspondientes antes de ejecutar [`gt stage`](/docs/cli/reference/commands/stage), [`gt upload`](/docs/cli/reference/commands/upload), [`gt enqueue`](/docs/cli/reference/commands/enqueue) y [`gt translate`](/docs/cli/reference/commands/translate), cuando estos comandos ponen nuevo trabajo en cola. Cuando `stageTranslations` está habilitado, [`gt translate`](/docs/cli/reference/commands/translate) solo descarga la versión preparada y no sincroniza las fuentes. Si falla la sincronización de fuentes, se emite una advertencia, pero la traducción no se detiene; el procesamiento de Lottie continúa con fuentes alternativas. Consulta [Cargar recursos del proyecto](/docs/platform/openapi/reference/project/upload-assets) para obtener información sobre la validación y el almacenamiento de fuentes.
## `publish` [#publish]
**Tipo** `boolean` · **Opcional** · **Predeterminado** `false`
Cuando es `true`, los archivos traducidos se publican en la CDN de General Translation después de [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload) o [`save-local`](/docs/cli/reference/commands/save-local). Las traducciones de Lottie siguen estando disponibles únicamente mediante descargas de la API y la CLI; establecer `publish` no hace que los archivos `.lottie` estén disponibles desde la CDN. Consulta [la publicación en la CDN](#cdn-publishing) para controlar esto por archivo y por comando.
```json title="gt.config.json"
{
"publish": true
}
```
## `stageTranslations` [#stage]
**Tipo** `boolean` · **Opcional** · **Predeterminado** `false`
Cuando es `true`, la CLI solo descarga las versiones enviadas con [`gt stage`](/docs/cli/reference/commands/stage). La CLI configura esta opción automáticamente la primera vez que ejecutas [`gt stage`](/docs/cli/reference/commands/stage). Usa el flujo de trabajo de preparación para la revisión humana y para formatos asíncronos como [Lottie](/docs/cli/reference/formats/lottie-files); la configuración de revisión del proyecto determina si las traducciones completadas también requieren aprobación.
## `requiresReview` [#requires-review]
**Tipo** `boolean` · **Opcional** · **Predeterminado** `false`
El valor predeterminado a nivel de proyecto para exigir revisión: cuando es `true`, los artefactos traducidos requieren aprobación antes de que el cliente los use. Debe ser un valor booleano; usa la clave [`files..requiresReview`](#files) por archivo (que acepta un booleano o globs `{ include, exclude }`) para las anulaciones por glob. La política por archivo tiene prioridad; los archivos que no coincidan ni con un glob de `include` ni con uno de `exclude` usarán este valor predeterminado de nivel superior.
```json title="gt.config.json"
{
"requiresReview": true
}
```
## `src` [#src]
**Tipo** `string[]` · **Opcional** · **Predeterminado** globs de archivos fuente específicos del framework
Una lista de patrones glob para los archivos fuente que se analizan en busca de contenido inline. Los proyectos de la familia React analizan JavaScript y TypeScript en `src`, `app`, `pages` y `components` de forma predeterminada. Los proyectos de Vue también analizan los archivos `*.vue` de la raíz, además de archivos JavaScript, TypeScript y Vue en los directorios convencionales de Vue y Nuxt como `composables`, `layouts`, `plugins`, `server`, `stores`, `utils` y `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` · **Opcional** · **Valor predeterminado** —
La ruta relativa de un archivo de diccionario. Si se omite, la CLI busca `dictionary.[json|ts|js]` en `./src` y `./`.
```json title="gt.config.json"
{
"dictionary": "./dictionary.json"
}
```
## `branchOptions` [#branch-options]
**Tipo** `object` · **Opcional** · **Predeterminado** —
Configura el seguimiento de traducciones por rama. Consulta [Seguimiento de traducciones por rama](/docs/cli/guides/branching). Los flags de la CLI tienen prioridad sobre estos valores.
| Propiedad | Descripción | Tipo | Opcional | Predeterminado |
| -------------------- | -------------------------------------------------------------- | --------- | -------- | -------------- |
| `enabled` | Activa el uso de ramas para el proyecto. | `boolean` | Sí | `false` |
| `currentBranch` | Sobrescribe el nombre de la rama detectada. | `string` | Sí | — |
| `autoDetectBranches` | Detecta las relaciones entre ramas entrantes y la rama actual. | `boolean` | Sí | `true` |
| `remoteName` | Remoto de Git usado para detectar ramas. | `string` | Sí | `origin` |
```json title="gt.config.json"
{
"branchOptions": {
"enabled": true,
"currentBranch": "my-feature-branch",
"autoDetectBranches": true,
"remoteName": "origin"
}
}
```
## `customMapping` [#custom-mapping]
**Tipo** `object` · **Opcional** · **Predeterminado** —
Asigna un alias a una configuración regional con un código diferente y, opcionalmente, anula sus propiedades. Por ejemplo, asigna el alias `cn` al código oficial `zh`.
Cuando uses un alias, establece `defaultLocale` y las entradas de `locales` con el nombre del alias (`cn`), no con el nombre canónico (`zh`).
```json title="gt.config.json"
{
"defaultLocale": "cn",
"locales": ["cn", "fr", "en"],
"customMapping": {
"cn": {
"code": "zh",
"name": "Mandarin"
}
}
}
```
## `options.saveLocal` [#save-local]
**tipo** `boolean` · **Optional** · **predeterminado** `false`
Detecta ediciones en los archivos de traducción locales descargados previamente y envía sus diffs antes de que [`gt translate`](/docs/cli/reference/commands/translate) o [`gt stage`](/docs/cli/reference/commands/stage) encolen nuevo trabajo. Defínelo dentro del objeto `options` de nivel superior. Los flags `--save-local` y `--no-save-local` reemplazan esta configuración durante una única ejecución.
```json title="gt.config.json"
{
"options": {
"saveLocal": true
}
}
```
### Historial de versiones
| Versión | Cambios |
| -------- | ---------------------------------------------------------------------------------------------------------------- |
| `2.20.3` | Las local edits pasaron a ser opt-in; establece esta clave en `true` o pasa `--save-local` para habilitar el step. |
## Publicación en CDN [#cdn-publishing]
De forma predeterminada, la CLI no publica en la CDN. Cuando la CDN está habilitada en la configuración de tu proyecto, puedes controlar la publicación de forma global, por archivo o por comando.
* **Global:** establece la opción [`publish`](#publish) de nivel superior en `true`, o pasa `--publish` a [`translate`](/docs/cli/reference/commands/translate), [`upload`](/docs/cli/reference/commands/upload) o [`save-local`](/docs/cli/reference/commands/save-local).
* **Solo archivos GT:** establece `publish: true` en `files.gt`.
* **Por archivo:** en una lista `include`, reemplaza una cadena glob por un objeto con `pattern` y `publish` para incluir o excluir explícitamente los archivos coincidentes.
```json title="gt.config.json"
{
"files": {
"json": {
"include": [
{ "pattern": "locales/[locale]/*.json", "publish": true },
{ "pattern": "locales/[locale]/internal/**/*.json", "publish": false }
]
}
}
}
```
Para cualquier archivo, la CLI resuelve la publicación en este orden: una exclusión explícita con `"publish": false`, luego una inclusión explícita con `"publish": true`, y después la configuración global de `publish`. Si no existe ninguna configuración de publicación en ningún nivel, se omite el paso de publicación.
## Locadex preserve local edits [#locadex-requirements]
Cuando una automation de Locadex tiene habilitada la opción **Preserve local edits**, configura `"publish": true` en el nivel superior o bien `files.gt.output`. Locadex lo valida antes de ejecutar la traducción.
```json title="gt.config.json"
{
"files": {
"gt": {
"output": "public/i18n/[locale].json"
}
}
}
```
La configuración por archivo y `files.gt.publish` no cumplen esta comprobación. Sin la publicación en CDN de nivel superior, `files.gt.output` le indica al workflow dónde se almacenan las traducciones GTJSON locales para que pueda preservar las ediciones.
## Configuración de ejemplo [#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"]
}
}
}
```
Una sola ejecución de [`gt translate`](/docs/cli/reference/commands/translate) con esta configuración traduce los archivos MDX de `content/docs/en` (que se guardan en `content/docs/fr` y `content/docs/es` como `.fr.mdx` y `.es.mdx`), los archivos JSON de `resources/en` (excepto `resources/en/exclude`) y cualquier componente [``](/docs/react/reference/components/t) inline, así como las entradas del diccionario. Las traducciones de GT se guardan en `public/i18n/fr.json` y `public/i18n/es.json`.
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.