Guía de uso
Guía de uso para la herramienta de línea de comandos GT
Descripción general
Esta guía te llevará paso a paso por el proceso de usar la herramienta de línea de comandos de General Translation (gtx-cli) para traducir tu proyecto.
La herramienta de línea de comandos es compatible con cualquier biblioteca de i18n, ya sea que estés usando gt-next, gt-react o bibliotecas de terceros como next-intl o react-i18next.
La herramienta de línea de comandos se encarga de conectar tu proyecto con el servicio de traducción por IA de General Translation.
Existen varias formas de usar la herramienta de línea de comandos; por favor, navega a la sección relevante según tu caso de uso.
Instalación
Para instalar la herramienta CLI, ejecuta el siguiente comando:
npm i --save-dev gtx-cliyarn add --dev gtx-clibun add --dev gtx-clipnpm add --save-dev gtx-cliCasos de uso
Traduciendo proyectos GT
La herramienta CLI se puede usar para traducir tus proyectos que utilizan gt-next o gt-react.
Esta guía asume que ya has configurado tu base de código para usar gt-next o gt-react según los tutoriales de gt-next o gt-react.
- Primero, necesitarás configurar los ajustes de GT de tu proyecto.
npx gtx-cli configureEste comando generará automáticamente una clave API y un ID de proyecto para tu proyecto a través del panel de control.
Sin embargo, si prefieres establecer manualmente la clave API y el ID de proyecto, sigue los pasos 2 y 3 a continuación.
- A continuación, deberás crear un proyecto en el panel de General Translation.
Después de crear un proyecto, deberás generar una clave API de producción. Navega a la página "API Keys" y haz clic en el botón "Create API Key".
- Luego, agrega tu clave API y el ID de proyecto a tus variables de entorno.
GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>- Finalmente, ejecuta el comando de traducción.
npx gtx-cli translatePor defecto, la herramienta CLI publicará las traducciones en el CDN de General Translation, para que estén listas para usarse en tu proyecto.
Si deseas desactivar este comportamiento (por ejemplo, si cargas las traducciones desde otra fuente), agrega la bandera --no-publish al comando.
Consulta la referencia de la API para más información sobre el comando translate.
Traduciendo archivos de idioma (librerías i18n de terceros o proyectos GT independientes)
La herramienta CLI te permite traducir archivos de idioma para librerías i18n de terceros o con una implementación independiente de gt-next o gt-react.
La mayoría de las librerías i18n dependen de archivos JSON para almacenar los datos de traducción. La herramienta CLI se puede usar para traducir automáticamente estos archivos JSON a los idiomas que desees.
- Primero, necesitarás configurar los ajustes de GT de tu proyecto.
npx gtx-cli configureEste comando creará un archivo gt.config.json en la raíz de tu proyecto, que contiene algunas configuraciones básicas, como el locale predeterminado de tu proyecto y los locales soportados.
Este comando generará automáticamente una clave API y un ID de proyecto para tu proyecto a través del panel de control.
Sin embargo, si prefieres establecer manualmente la clave API y el ID de proyecto, sigue los pasos 2 y 3 a continuación.
- A continuación, deberás crear un proyecto en el panel de General Translation.
Después de crear un proyecto, deberás generar una clave API de producción. Navega a la página "API Keys" y haz clic en el botón "Create API Key".
- Luego, agrega tu clave API y el ID de proyecto a tus variables de entorno.
GT_API_KEY=<your-api-key>
GT_PROJECT_ID=<your-project-id>- Finalmente, ejecuta el comando de traducción.
npx gtx-cli translatePor defecto, la herramienta CLI buscará archivos para traducir según la propiedad files en tu archivo gt.config.json.
Usará el defaultLocale especificado en tu archivo gt.config.json como el idioma fuente.
Los archivos traducidos se guardarán en la ubicación de salida correspondiente especificada en tu archivo gt.config.json.
Consulta la documentación de configuración para más información sobre la propiedad files.
Generar archivos de idioma para proyectos GT
La herramienta CLI puede usarse para generar archivos de idioma para proyectos que utilizan gt-next o gt-react.
Este caso de uso es útil si deseas utilizar tu propio proveedor de traducciones.
A diferencia de otras librerías de i18n, gt-next y gt-react soportan traducciones en línea, lo que significa que no existe una estructura tradicional de archivos JSON con claves y valores para cada idioma.
Esto significa que, para poder rastrear los cambios en el texto, las librerías GT almacenan los hashes del texto original en el código fuente.
Esta estructura de datos interna (que contiene hashes) es difícil de manejar, por lo que la herramienta CLI proporciona un comando útil para generar archivos de idioma para tu proyecto.
- Primero, necesitarás configurar los ajustes de GT en tu proyecto.
npx gtx-cli configureCuando se te pregunte si deseas guardar las traducciones en el GT CDN, selecciona la opción "No".
- Ejecuta:
npx gtx-cli generateEste comando generará un archivo fuente para tu localización predeterminada y para todas las demás localizaciones que hayas configurado en tu proyecto.
El contenido de cada archivo es el mismo y se fusionará con cualquier traducción previa que tengas en tu proyecto.
Consulta la referencia de la API para más información sobre el comando generate.
Notas
gtx-cli translatese utiliza para generar automáticamente traducciones para tu proyecto.- Si estás usando una biblioteca i18n de terceros, puedes actualizar automáticamente todos tus archivos JSON de traducción cada vez que tu proyecto cambie. Solo tienes que agregar el comando
gtx-cli translatea tu proceso de compilación o CD antes del comando de compilación para añadir automáticamente las traducciones a tu proyecto.
Próximos pasos
- Consulta la referencia de la API de CLI para más información.
- Si quieres ver traducciones en vivo durante el desarrollo (como recarga en caliente), revisa el componente
<T>.
¿Qué te parece esta guía?