# gt: General Translation CLI tool: Translate
URL: https://generaltranslation.com/es/docs/cli/translate.mdx
---
title: Translate
description: Cómo traducir tu proyecto
---
## Uso
```bash
npx gt translate
```
**Importante:** Ejecuta esto en tu flujo de CI **antes** de compilar la aplicación para producción.
## Descripción general
El comando `gt translate` traduce tu proyecto leyendo el archivo `gt.config.json` para determinar qué archivos debe traducir.
Si usas [`gt-next`](/docs/next), [`gt-react`](/docs/react), o [`gt-react-native`](/docs/react-native), también buscará contenido inline en el código fuente de tu proyecto (como componentes `` y hooks `useGT`) y generará los archivos de traducción necesarios.
Además, incluye el contenido del archivo de diccionario (si se proporciona).
Este comando es la forma principal de usar la API de General Translation y los servicios relacionados.
**Solo para uso en producción:** Este comando está pensado para compilaciones de producción y **no debe usarse en desarrollo**.
Antes de ejecutar este comando, asegúrate de estar en la rama que se usará en producción.
Establece tu clave de API de producción (`GT_API_KEY`) y el ID del proyecto (`GT_PROJECT_ID`) como variables de entorno.
**Nota:** Se requiere una clave de API de producción. Obtén una gratis en [generaltranslation.com](https://generaltranslation.com/dashboard), o ejecuta el [asistente de configuración](/docs/cli/init) para generar una.
### Traduce tu proyecto [#translate]
```bash
npx gt translate
```
El comando `translate` lee tu archivo `gt.config.json` para determinar qué archivos traducir y también busca contenido traducible en el código fuente de tu proyecto antes de generar los archivos de traducción necesarios.
Las traducciones se guardan automáticamente en tu base de código.
Consulta la [documentación de configuración](/docs/cli/reference/config#files) para obtener más detalles.
{/* These links point to our own SDK docs intentionally — we want to show how our CLI handles these libraries, not link to the external library sites */}
**Detección automática:** Si usas [`next-intl`](/docs/next), [`react-i18next`](/docs/react), o
[`next-i18next`](/docs/react-native), la herramienta de CLI detectará
automáticamente tu biblioteca de i18n leyendo tu archivo `package.json` y traducirá tus
archivos JSON respetando la sintaxis de tu biblioteca de i18n.
### Validar sin traducir [#validate]
```bash
npx gt translate --dry-run
```
Si usas [`gt-next`](/docs/next), [`gt-react`](/docs/react), o [`gt-react-native`](/docs/react-native), puedes usar esto para validar los componentes `` y el archivo de diccionario de tu proyecto sin generar traducciones.
***
## Opciones
| Parámetro | Descripción | Tipo | Predeterminado |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--api-key` | Especifica una clave de API de producción | `string` | |
| `--project-id` | Especifica el ID del proyecto | `string` | |
| `--version-id` | Especifica un ID de versión (de forma predeterminada, un hash del contenido) | `string` | |
| `--config ` | Especifica una ruta al archivo de configuración de GT | `string` | `"gt.config.json"` |
| `--tsconfig, --jsconfig ` | Especifica una ruta al archivo de configuración de TS o JS | `string` | |
| `--src ` | Patrones glob separados por espacios para archivos de origen (relativos a la raíz) | `[string]` | `['src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}']` |
| `--dictionary ` | Especifica una ruta al archivo de diccionario | `string` | |
| `--inline` | Incluye etiquetas `` inline, además del diccionario | `boolean` | `true` |
| `--timeout` | Tiempo de espera de la solicitud de traducción, en segundos | `number` | `900` |
| `--new, --locales ` | Configuraciones regionales de destino (se añaden a `locales` de `gt.config.json`) | `[string]` | |
| `--default-locale ` | La configuración regional de origen del proyecto | `string` | `en` |
| `--ignore-errors` | Ignora los errores y fuerza la traducción del contenido válido | `flag` | `false` |
| `--dry-run` | Valida sin traducir | `flag` | `false` |
| `--force` | Fuerza la retraducción de todo el contenido | `flag` | `false` |
| `--force-download` | Fuerza la descarga de todas las traducciones | `flag` | `false` |
| `--save-local` | Detecta y guarda las ediciones locales antes de poner en cola las traducciones | `flag` | `false` |
| `--enable-branching` | Habilita la bifurcación para el proyecto | `flag` | `false` |
| `--branch ` | Especifica un nombre de rama personalizado para las traducciones | `string` | |
| `--disable-branch-detection` | Desactiva la detección automática de ramas | `flag` | `false` |
| `--tag [value]` | Etiqueta esta ejecución de traducción (se resuelve automáticamente desde git si no se proporciona ningún valor) | `string` | |
| `-m, --message ` | Mensaje para adjuntar a la etiqueta de traducción | `string` | |
| `--publish` | Publica las traducciones en la CDN después de traducir | `flag` | `false` |
| `--remote-name ` | Especifica un nombre remoto personalizado para la detección de ramas | `string` | `"origin"` |
**Seguridad:** No agregues tu clave de API al archivo `gt.config.json`. En su lugar, configúrala como una variable de entorno. La CLI lee automáticamente `GT_API_KEY` si está configurada.
### Opciones principales
| Opción | Descripción |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dry-run` | Analiza y valida tu proyecto sin comunicarte con la API de GT. Es útil para validar tu base de código. |
| `--force` | Vuelve a traducir todo el contenido y sobrescribe las traducciones existentes. Se perderán todos los cambios locales. Se te cobrarán las nuevas traducciones. |
| `--force-download` | Vuelve a descargar todas las traducciones y sobrescribe los cambios locales. No vuelve a traducir. |
| `--save-local` | Detecta y guarda las ediciones locales en los archivos de traducción antes de ponerlas en cola. Consulta [`save-local`](/docs/cli/save-local). |
| `--enable-branching` | Hace un seguimiento de las traducciones por separado para distintas ramas de Git. Consulta [bifurcación](/docs/cli/branching). |
| `--tag` | Etiqueta una ejecución de traducción con un identificador fácil de leer para el seguimiento de versiones. Consulta [Etiquetado](#tagging). |
| `-m, --message` | Adjunta un mensaje descriptivo a una etiqueta de traducción. Consulta [Etiquetado](#tagging). |
| `--publish` | Publica las traducciones en la CDN para cargarlas en tiempo de ejecución. Consulta [publicación en la CDN](#publishing-to-the-cdn). |
### Archivo de configuración
Cuando ejecutes la CLI por primera vez, intentará crear un archivo `gt.config.json` en la raíz de tu proyecto. Lee más sobre la configuración [aquí](/docs/cli/reference/config).
## Consejos importantes
### Fuentes de contenido
El comando `translate` busca de forma recursiva contenido traducible en tu proyecto.
De forma predeterminada, busca en los siguientes directorios:
* `./src`
* `./app`
* `./pages`
* `./components`
Puedes especificar otros directorios con la opción `--src` o modificar la propiedad `src` en tu archivo [`gt.config.json`](/docs/cli/reference/config).
### Sobrescribir traducciones
De forma predeterminada, la CLI no sobrescribirá los cambios locales en las traducciones, a menos que el contenido fuente haya cambiado.
Para retraducir contenido ya traducido, usa `--force`.
**Precaución:** `--force` **sobrescribirá todas las traducciones existentes y generará otras nuevas**. Se perderán todos los cambios locales. Se te cobrarán las nuevas traducciones.
Para volver a descargar las traducciones sin retraducir, usa `--force-download`.
**Precaución:** `--force-download` sobrescribirá los cambios locales en las traducciones y descargará las traducciones más recientes. No retraducirá ningún contenido.
### Etiquetado [#tagging]
Usa las opciones `--tag` y `-m` para etiquetar ejecuciones de traducción con identificadores fáciles de reconocer, lo que facilita el seguimiento y la identificación de versiones en el panel de control.
#### Etiquetar con un identificador personalizado
```bash
npx gt translate --tag v2.1.0
```
#### Etiquetado con un identificador y un mensaje personalizados
```bash
npx gt translate --tag v2.1.0 -m "Added checkout page translations"
```
#### Etiquetado automático con git
Pasa `--tag` sin valor para usar automáticamente el hash del commit actual de git como id de la etiqueta y el mensaje del commit como mensaje de la etiqueta:
```bash
npx gt translate --tag
```
Puedes reemplazar el mensaje de commit por uno personalizado:
```bash
npx gt translate --tag -m "Release 2.1 translations"
```
#### Etiquetado solo del mensaje
Si pasas `-m` sin `--tag`, se genera automáticamente una etiqueta a partir del hash del commit actual de Git (o de un identificador aleatorio si no estás en un repositorio Git):
```bash
npx gt translate -m "Weekly translation update"
```
El etiquetado no bloquea el proceso; si falla la creación de etiquetas, la ejecución de la traducción continúa normalmente.
### Publicación en la CDN [#publishing-to-the-cdn]
De forma predeterminada, `gt translate` guarda los archivos de traducción localmente en tu base de código. Usa la opción `--publish` para publicar también las traducciones en la CDN de General Translation, lo que permite cargar traducciones en tiempo de ejecución sin tener que empaquetar archivos con tu aplicación.
```bash
npx gt translate --publish
```
Esto es útil para proyectos de `gt-next` que cargan las traducciones desde la CDN en tiempo de ejecución en lugar de hacerlo desde archivos locales.
**La CDN debe estar habilitada:** Antes de usar `--publish`, habilita la CDN en la configuración de tu proyecto en [generaltranslation.com/dashboard](https://generaltranslation.com/dashboard). Si la CDN no está habilitada, el comando traducirá correctamente, pero no se publicará y mostrará una advertencia.
Puedes combinar `--publish` con la salida a archivos locales: las traducciones se guardarán localmente *y* se publicarán en la CDN:
```bash
npx gt translate --publish
```
### Archivo de diccionario
El comando `translate` detecta automáticamente el archivo de diccionario en tu proyecto.
De forma predeterminada, busca un archivo llamado `dictionary.[json|ts|js]` en:
* `./src`
* `./`
Puedes especificar otro archivo de diccionario con la opción `--dictionary` o modificar la propiedad `dictionary` en tu archivo [`gt.config.json`](/docs/cli/reference/config).