# gt: General Translation CLI tool: Configuración URL: https://generaltranslation.com/es/docs/cli/reference/config.mdx --- title: Configuración description: Documentación de configuración del archivo gt.config.json --- ## Descripción general El archivo `gt.config.json` se usa para configurar los ajustes de GT de tu proyecto. Debe colocarse en la raíz del proyecto. El asistente de configuración de la CLI [`npx gt init`](/docs/cli/init) creará un archivo `gt.config.json` en tu proyecto. ## Configuración El archivo `gt.config.json` acepta las siguientes propiedades, entre otras: * `defaultLocale`: La configuración regional predeterminada de tu proyecto. Es la configuración regional en la que está escrito tu contenido fuente. También es la configuración regional de respaldo de tu proyecto (si usas `gt-next` o `gt-react`). * `locales`: Un arreglo de configuraciones regionales de tu proyecto. Son las configuraciones regionales a las que quieres traducir tu proyecto. Consulta las [configuraciones regionales compatibles](/docs/platform/supported-locales) para obtener más información. Si usas `gt-next` o `gt-react`, estas también son las configuraciones regionales compatibles con tu aplicación. * `files`: Es un objeto que contiene información sobre el contenido que quieres traducir. * `publish`: Un indicador booleano opcional. Cuando es `true`, los archivos traducidos se publican en la CDN de GT después de ejecutar `translate`, `upload` o `save-local`. El valor predeterminado es `false` (sin publicación). También se puede establecer para cada comando con `--publish`. Consulta [publicación en la CDN](#cdn-publishing) para obtener más detalles. * `stageTranslations`: Un indicador booleano opcional que indica si tu proyecto está configurado para usar revisión humana. * `src`: Un arreglo opcional de patrones glob para tus archivos fuente. De forma predeterminada, se establece en: ```json [ "src/**/*.{js,jsx,ts,tsx}", "app/**/*.{js,jsx,ts,tsx}", "pages/**/*.{js,jsx,ts,tsx}", "components/**/*.{js,jsx,ts,tsx}" ] ``` * `dictionary`: Una cadena opcional que especifica la ruta relativa del archivo de diccionario. * `branchOptions`: Un objeto opcional para configurar el seguimiento de traducciones basado en ramas. Consulta [branching](/docs/cli/branching) para obtener más información. Para ayudarte a validar tu archivo `gt.config.json`, puedes usar el [esquema JSON](https://assets.gtx.dev/config-schema.json) de la CLI. Agrégalo al inicio de tu archivo `gt.config.json`: ```json title="gt.config.json" copy { "$schema": "https://assets.gtx.dev/config-schema.json" } ``` Aquí tienes la estructura básica del archivo `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 para una configuración regional Si quieres asignar un alias a una configuración regional (por ejemplo, `cn` en lugar de `zh`), puedes especificar una asignación personalizada en el archivo `gt.config.json`. ```json title="gt.config.json" { "customMapping": { // La configuración regional alias "cn": { "code": "zh" // El código de configuración regional BCP 47 oficial } } } ``` También puedes especificar atributos diferentes para la configuración regional con alias. ```json title="gt.config.json" { "customMapping": { "cn": { "code": "zh", "name": "Mandarin" } } } ``` ### Opciones de branch Si quieres configurar las opciones de branch en tu archivo de configuración, puedes usar el objeto `branchOptions`: ```json title="gt.config.json" { "branchOptions": { "enabled": true, "currentBranch": "my-feature-branch", "autoDetectBranches": true, "remoteName": "origin" } } ``` | Propiedad | Descripción | Predeterminado | | -------------------- | --------------------------------------------------------------------------------- | -------------- | | `enabled` | Habilita el branching para el proyecto | `false` | | `currentBranch` | Sobrescribe el nombre del branch actual (en lugar de detectarlo automáticamente) | `undefined` | | `autoDetectBranches` | Detecta automáticamente las relaciones entre branches (de entrada y con checkout) | `true` | | `remoteName` | El nombre del remoto de Git usado para detectar branches | `"origin"` | Los flags de la CLI tienen prioridad sobre las opciones del archivo de configuración. Consulta la [guía de branching](/docs/cli/branching) para más detalles. *** ## `files` ### Tipos de archivo compatibles `files` debe contener una clave para cada tipo de archivo que quieras traducir. Puedes configurar tu proyecto para combinar distintos tipos de archivo y hacer que todos se traduzcan. Actualmente admitimos los siguientes tipos de archivo: * `gt`: Archivos de General Translation. Los usan [`gt-next`](/docs/next), [`gt-react`](/docs/react) y [`gt-react-native`](/docs/react-native). * `json`: Archivos JSON. * `pot`: Archivos PO/POT (gettext). * `yaml`: Archivos YAML. * `mdx`: Archivos de componentes Markdown (MDX). * `md`: Archivos Markdown (MD). * `js`: Archivos JavaScript. * `ts`: Archivos TypeScript. * `html`: Archivos HTML. * `txt`: Archivos de texto. * `twilioContentJson`: Archivos JSON de Twilio Content. Se usan para traducir [Twilio Content Templates](https://www.twilio.com/docs/content). Cada tipo de archivo debe corresponder a un objeto que contenga una o más de las siguientes claves: * `include` * `exclude` * `transform` * `transformationFormat` * `output` ### `include` Si se usa, el valor de la clave `include` debe ser un arreglo de patrones glob que coincidan con los archivos que quieras traducir. Debes usar el marcador de posición `[locale]` en tus patrones glob para asegurarte de que los archivos de origen se encuentren correctamente y de que los archivos traducidos se guarden en la ubicación correcta. La herramienta de CLI reemplazará el marcador de posición `[locale]` por el valor de `defaultLocale` al buscar archivos traducibles. La herramienta de CLI guardará los archivos traducidos en la ruta correspondiente, con el marcador de posición `[locale]` reemplazado por el código de configuración regional de destino. ```json { "include": ["docs/[locale]/**/*.json"] } ``` ### `exclude` Si se usa, el valor de la clave `exclude` debe ser un arreglo de patrones glob que coincidan con los archivos que quieres excluir de la traducción. El patrón es el mismo que el de `include`, con la salvedad de que el marcador de posición `[locale]` es opcional. Si se proporciona, se reemplazará por el valor de `defaultLocale`. ```json { "exclude": ["docs/[locale]/exclude/**/*.json"] } ``` Si quieres excluir archivos de la traducción en todas las configuraciones regionales, puedes usar el marcador de posición `[locales]` en lugar de `[locale]`. ```json { "exclude": ["docs/[locales]/exclude/**/*.json"] } ``` ### `transform` `transform` puede ser una cadena o un objeto. Si `transform` es una cadena, define un remapeo del nombre de archivo. Debe contener un comodín `*` que se sustituirá por el nombre original del archivo (todo lo que aparece antes del primer `.`). Por ejemplo, si quieres que la extensión de todos tus archivos traducidos sea `.[locale].json` en lugar de `.json`, puedes usar la siguiente configuración: ```json { "transform": "*.[locale].json" } ``` Como alternativa, si `transform` es un objeto, debe contener las siguientes propiedades: * `match` (opcional): Un patrón regex para buscar coincidencias en cadenas; admite grupos de captura * `replace` (obligatorio): Cadena o patrón regex con el que reemplazar la coincidencia Ambos valores admiten grupos de captura regex y se aplican al nombre de archivo relativo completo del archivo de salida. ```json { "transform": { "match": "^(.*)$", "replace": "{locale}/$1" } } ``` Por ejemplo, la configuración anterior hará que los archivos traducidos se guarden en un subdirectorio correspondiente a la configuración regional de destino. #### Marcadores de posición especiales La opción `transform` admite varios marcadores de posición especiales que pueden usarse tanto en las cadenas `match` como en `replace`: * `{locale}`: el marcador de posición del código de configuración regional, cuyo comportamiento varía según el contexto: * **En las cadenas `match`**: se sustituye por el código de configuración regional predeterminado (por ejemplo, `"en"`) para ayudar a identificar los archivos de origen * **En las cadenas `replace`**: se sustituye por el código de configuración regional de destino (por ejemplo, `"fr"`, `"es"`) en los archivos traducidos de salida Por ejemplo, si tu configuración regional predeterminada es `"en"` y estás traduciendo a `"fr"`: * Un patrón `match` como `"content/{locale}/file.md"` se convierte en `"content/en/file.md"` * Un patrón `replace` como `"content/{locale}/file.md"` se convierte en `"content/fr/file.md"` Además, cualquier otra propiedad de `getLocaleProperties` puede usarse como marcador de posición con el mismo comportamiento dependiente del contexto. Esto resulta útil si tu documentación o framework de i18n requiere una extensión de archivo específica para los archivos traducidos, en lugar de un enrutamiento por subdirectorios según la configuración regional. ### `transformationFormat` La clave `transformationFormat` especifica un formato de archivo distinto para los archivos traducidos de salida. Esto resulta útil cuando tus archivos de origen son templates que deben generar un tipo de archivo diferente después de la traducción. Por ejemplo, los archivos POT (PO Template) son templates de origen, pero la salida traducida debe ser archivos PO: ```json { "files": { "pot": { "include": ["locales/[locale]/**/*.pot"], "transformationFormat": "PO" } } } ``` El valor debe ser una cadena que coincida con una de las claves de los formatos de archivo compatibles (p. ej., `"PO"`). ### `output` Esta clave se usa exclusivamente para archivos de General Translation, en concreto para guardar las traducciones localmente. Si usas la CDN de GT, esta clave no es necesaria. El valor debe ser una cadena que contenga un marcador de posición `[locale]` que indique la ubicación donde se guardarán las traducciones. Por ejemplo, si quieres guardar tus traducciones al español en un archivo llamado `ui.es.json` dentro del directorio `public/i18n`, debes usar la siguiente cadena: ```json { "output": "public/i18n/[locale].json" } ``` Esta opción solo debe usarse si estás usando `gt-next` o `gt-react` y quieres guardar las traducciones localmente, en lugar de usar la CDN de GT. Actualmente, solo se puede generar un archivo por cada configuración regional. *** ### Tipo de archivo: `gt` [#gt] **Claves admitidas** * `output` (Obligatorio) **Ejemplo** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "gt": { "output": "public/i18n/[locale].json" } } } ``` Esta configuración le indica a la herramienta CLI que guarde sus traducciones al francés y al español en el directorio `public/i18n/[locale].json`. De forma predeterminada, la herramienta CLI no publicará sus traducciones en la CDN de GT con esta configuración. *** ### Tipo de archivo: `json` [#json] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "json": { "include": ["json_files/[locale]/**/*.json"], "exclude": ["json_files/[locale]/exclude/**/*.json"] } } } ``` Supongamos que la configuración regional predeterminada de tu proyecto es `en` y que quieres traducirlo a `fr` y `es`. Con esta configuración, la CLI buscará todos los archivos JSON en el subdirectorio `json_files/en/` y guardará los archivos traducidos en `json_files/fr/` y `json_files/es/`. Ignorará cualquier archivo del subdirectorio `json_files/en/exclude/`. *** ### Tipo de archivo: `yaml` [#yaml] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "yaml": { "include": ["yaml_files/[locale]/**/*.yaml"], "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"] } } } ``` Supongamos que la configuración regional predeterminada de tu proyecto es `en` y que quieres traducirlo a `fr` y `es`. Con esta configuración, la CLI buscará todos los archivos YAML del subdirectorio `yaml_files/en/` y guardará los archivos traducidos en `yaml_files/fr/` y `yaml_files/es/`. Ignorará cualquier archivo del subdirectorio `yaml_files/en/exclude/`. *** ### Tipo de archivo: `mdx` [#mdx] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["ja"], "files": { "mdx": { "include": ["content/docs/[locale]/**/*.mdx"], "transform": "*.[locale].mdx" } } } ``` Esta configuración indicará a la herramienta CLI que busque todos los archivos MDX dentro del directorio `content/docs/en` y guarde los archivos traducidos en el directorio `content/docs/ja`. La clave `transform` hace que la extensión de los archivos traducidos cambie a `.ja.mdx`. *** ### Tipo de archivo: `md` [#md] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```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" } } } ``` Esta configuración indicará a la herramienta CLI que busque todos los archivos MD en el directorio `content/docs/en` y guarde los archivos traducidos en el directorio `content/docs/ja`. La clave `transform` hace que la extensión de los archivos traducidos cambie a `.ja.md`. Se ignorarán todos los archivos del directorio `content/docs/en/exclude`. *** ### Tipo de archivo: `js` [#js] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "js": { "include": ["scripts/[locale]/**/*.js"] } } } ``` Esta configuración le indicará a la herramienta CLI que busque todos los archivos JavaScript dentro del directorio `scripts/en` y guarde los archivos traducidos en los directorios `scripts/fr` y `scripts/es`. *** ### Tipo de archivo: `ts` [#ts] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["fr", "es"], "files": { "ts": { "include": ["scripts/[locale]/**/*.ts"] } } } ``` Esta configuración le indicará a la herramienta CLI que busque todos los archivos TypeScript en el directorio `scripts/en` y guarde los archivos traducidos en los directorios `scripts/fr` y `scripts/es`. *** ### Tipo de archivo: `html` [#html] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```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" } } } ``` Esta configuración le indicará a la herramienta CLI que busque todos los archivos HTML dentro del directorio `content/docs/en` y guarde los archivos traducidos en el directorio `content/docs/ja`. La clave `transform` hace que la extensión de los archivos traducidos cambie a `.ja.html`. Se ignorarán todos los archivos del directorio `content/docs/en/exclude`. *** ### Tipo de archivo: `txt` [#txt] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```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" } } } ``` Esta configuración le indica a la herramienta de CLI que busque todos los archivos de texto en el directorio `content/docs/en` y guarde los archivos traducidos en el directorio `content/docs/ja`. La clave `transform` hace que la extensión de los archivos traducidos cambie a `.ja.txt`. Se ignorarán todos los archivos del directorio `content/docs/en/exclude`. *** ### Tipo de archivo: `twilioContentJson` [#twilioContentJson] **Claves admitidas** * `include` (Obligatorio) * `exclude` (Opcional) * `transform` (Opcional) **Ejemplo** ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["es", "fr"], "files": { "twilioContentJson": { "include": ["twilio/[locale]/**/*.json"] } } } ``` Esta configuración le indicará a la herramienta de CLI que busque todos los archivos JSON de Twilio Content en el directorio `twilio/en` y guarde los archivos traducidos en los directorios `twilio/es` y `twilio/fr`. Los archivos JSON de Twilio Content son templates estructurados que usa el [Content Template Builder de Twilio](https://www.twilio.com/docs/content) para mensajes de WhatsApp, SMS y RCS. La CLI traduce los valores de cadena visibles para el usuario (texto del cuerpo, etiquetas de botones y títulos de tarjetas) mientras conserva la estructura del template, los marcadores de posición de las variables y los campos no traducibles. *** ## Publicación en la CDN [#cdn-publishing] De forma predeterminada, la CLI no publica los archivos traducidos en la CDN de GT. Si has habilitado la CDN en la configuración del proyecto, puedes controlar la publicación de forma global, por archivo o por comando. ### Indicador global de publicación Define `publish` en el nivel superior para publicar **todos** los archivos traducidos en la CDN: ```json title="gt.config.json" { "publish": true } ``` También puedes pasar `--publish` a los comandos `translate`, `upload` o `save-local`: ```bash npx gt translate --publish ``` ### Opción `publish` de GT JSON Para publicar solo el formato interno de traducción de GT, usa la clave `publish` dentro de `files.gt`: ```json title="gt.config.json" { "files": { "gt": { "output": "public/i18n/[locale].json", "publish": true } } } ``` ### Control de publicación por archivo Para otros tipos de archivo (`json`, `yaml`, `mdx`, `md`, `po`, `xliff`, `csv`, `properties`), puedes controlar la publicación de cada archivo usando un objeto en el arreglo `include` en lugar de una simple cadena glob: ```json title="gt.config.json" { "files": { "json": { "include": [ { "pattern": "locales/[locale]/*.json", "publish": true }, { "pattern": "locales/[locale]/internal/**/*.json", "publish": false } ] } } } ``` Cada elemento de `include` puede ser: * Una **cadena** — un patrón glob (sin preferencia de publicación; usa la configuración global de `publish`) * Un **objeto** con `pattern` (glob) y `publish` (booleano) — incluye o excluye explícitamente los archivos coincidentes ### Orden de resolución Para cualquier archivo, la CLI determina si debe publicarse en este orden: 1. **Exclusión explícita** — el archivo coincide con una entrada de `include` con `"publish": false` → no se publica o se elimina de la CDN 2. **Inclusión explícita** — el archivo coincide con una entrada de `include` con `"publish": true` → se publica en la CDN 3. **Respaldo global** — usa la opción `publish` de nivel superior (el valor predeterminado es `false` si no está configurada) Si no existe ninguna configuración de publicación en ningún nivel, el paso de publicación se omite por completo. *** ## Configuración de ejemplo Desglosemos un archivo `gt.config.json` de ejemplo: ```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"] } } } ``` En este ejemplo, traducimos los siguientes archivos con una sola llamada a [`gt translate`](/docs/cli/translate): * Todos los archivos MDX del directorio `content/docs/en`. * Todos los archivos JSON del directorio `resources/en` (excepto los archivos del directorio `resources/en/exclude`). * Todos los componentes `` inline de tu proyecto de React o Next.js. * Tu archivo `dictionary.[json|js|ts]`. GT: Las traducciones se guardarán en `public/i18n/es.json` y `public/i18n/fr.json`. Estos archivos se pueden cargar con [`loadTranslations`](/docs/react/api/config/load-translations). MDX: Las traducciones se guardarán en los directorios `content/docs/fr` y `content/docs/es`. Las extensiones de archivo cambiarán a `.fr.mdx` y `.es.mdx`, respectivamente (en lugar de `.mdx`). JSON: Las traducciones se guardarán en los directorios `resources/fr` y `resources/es`. *** ## Siguientes pasos Aprende a usar el [comando init](/docs/cli/init) para generar este archivo de configuración.