# 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 --- ## Resumen El archivo `gt.config.json` se usa para configurar la configuración de GT de tu proyecto. Debe colocarse en la carpeta raíz de tu 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. Esta es la configuración regional en la que está escrito el contenido de origen. También es la configuración regional alternativa de tu proyecto (si usas `gt-next` o `gt-react`). * `locales`: Un array 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`: Una opción booleana 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 CDN](#cdn-publishing) para obtener más detalles. * `stageTranslations`: Una opción booleana opcional que indica si tu proyecto está configurado para usar revisión humana. * `src`: Un array opcional de patrones glob de archivos para tus archivos fuente. Por defecto, 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 [uso de ramas](/docs/cli/branching) para obtener más detalles. Para ayudarte a validar tu archivo `gt.config.json`, puedes usar el [JSON Schema](https://assets.gtx.dev/config-schema.json) de la CLI. Agrégalo al principio de tu archivo `gt.config.json`: ```json title="gt.config.json" copy { "$schema": "https://assets.gtx.dev/config-schema.json" } ``` Aquí tienes una 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 de configuración regional Si quieres usar un alias para 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": { // El alias de configuración regional "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 rama Si quieres configurar las opciones de uso de ramas 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 uso de ramas en el proyecto | `false` | | `currentBranch` | Sobrescribe el nombre de la rama actual (en lugar de detectarlo automáticamente) | `undefined` | | `autoDetectBranches` | Detecta automáticamente las relaciones entre ramas (entrantes y rama de origen) | `true` | | `remoteName` | El nombre del remoto de Git usado para detectar ramas | `"origin"` | Las opciones de la CLI tienen prioridad sobre las opciones del archivo de configuración. Consulta la [guía de uso de ramas](/docs/cli/branching) para obtener 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 mezclar distintos tipos de archivo y traducirlos todos. Actualmente admitimos los siguientes tipos de archivo: * `gt`: archivos de General Translation. Usados por [`gt-next`](/docs/next), [`gt-react`](/docs/react) y [`gt-react-native`](/docs/react-native). * `json`: archivos JSON. * `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` * `output` ### `include` Si se usa, el valor de la clave `include` debe ser un array 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 fuente se encuentren correctamente y de que los archivos traducidos se guarden en la ubicación correcta. La herramienta CLI reemplazará el marcador de posición `[locale]` por el valor de `defaultLocale` al buscar archivos traducibles. La herramienta CLI guardará los archivos traducidos en la ruta correspondiente, con el marcador de posición `[locale]` reemplazado por el código de la configuración regional de destino. ```json { "include": ["docs/[locale]/**/*.json"] } ``` ### `exclude` Si se usa, el valor de la clave `exclude` debe ser un array de patrones glob que coincidan con los archivos que quieras excluir de la traducción. El patrón es el mismo que el patrón `include`, con la excepción 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 para 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 del archivo. Debe contener un comodín `*` que se reemplazará por el nombre original del archivo (todo lo que esté 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" } ``` Alternativamente, si `transform` es un objeto, debe contener las siguientes propiedades: * `match` (opcional): Un patrón regex para hacer coincidir cadenas; admite grupos de captura * `replace` (obligatorio): Cadena o patrón regex para reemplazar la coincidencia Ambos valores admiten grupos de captura regex y se aplican al nombre 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 las cadenas `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 reemplaza por el código de configuración regional predeterminado (p. ej., `"en"`) para ayudar a identificar los archivos fuente * **En las cadenas `replace`**: se reemplaza por el código de configuración regional de destino (p. ej., `"fr"`, `"es"`) en los archivos de salida traducidos 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 tu framework de i18n requiere una extensión de archivo específica para los archivos traducidos, en lugar de un enrutamiento por configuración regional mediante subdirectorios. ### `output` Esta clave se usa exclusivamente para archivos de General Translation, en concreto para guardar las traducciones de forma local. 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 utilizas `gt-next` o `gt-react` y quieres guardar las traducciones de forma local, 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 indicará a la herramienta CLI que guarde las traducciones al francés y al español en el directorio `public/i18n/[locale].json`. Por defecto, la herramienta CLI no publicará las 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 dentro del 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 quieres traducir tu proyecto 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` (Obligatoria) * `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 le 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` (Obligatoria) * `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 en el directorio `scripts/en` y guarde los archivos traducidos en los directorios `scripts/fr` y `scripts/es`. *** ### Tipo de archivo: `ts` [#ts] **Claves admitidas** * `include` (Obligatoria) * `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 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 indicará a la herramienta 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` (Obligatoria) * `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 CLI que busque todos los archivos JSON de Twilio Content dentro del directorio `twilio/en` y guarde los archivos traducidos en los directorios `twilio/es` y `twilio/fr`. Los archivos JSON de Twilio Content son plantillas estructuradas que utiliza [Twilio's Content Template Builder](https://www.twilio.com/docs/content) para la mensajería 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 preserva la estructura de la plantilla, los marcadores de posición de las variables y los campos no traducibles. *** ## Publicación en CDN [#cdn-publishing] Por defecto, la CLI no publica los archivos traducidos en la CDN de GT. Si has habilitado la CDN en la configuración de tu proyecto, puedes controlar la publicación de forma global, por archivo o por comando. ### Marca de publicación global Establece `publish` en el nivel superior para publicar **todos** los archivos traducidos en la CDN: ```json title="gt.config.json" { "publish": true } ``` También puedes usar `--publish` con los comandos `translate`, `upload` o `save-local`: ```bash npx gt translate --publish ``` ### Marca de publicación para JSON de GT 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 array `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 entrada 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 un archivo determinado, la CLI resuelve si debe publicarse en este orden: 1. **Exclusión explícita** — el archivo coincide con una entrada de inclusión con `"publish": false` → no se publica o se elimina de la CDN 2. **Inclusión explícita** — el archivo coincide con una entrada de inclusión con `"publish": true` → se publica en la CDN 3. **Alternativa global** — usa la configuración `publish` de nivel superior (el valor predeterminado es `false` si no se establece) 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 Veamos en detalle 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 `` en línea 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.