gt@2.23.0 / @generaltranslation/api@0.5.0

gt@2.23.0 incorpora a la terminal el inicio de sesión en la cuenta, la selección de Projects, la creación de claves con permisos restringidos y una configuración automatizable mediante scripts. Las versiones complementarias @generaltranslation/api@0.5.0 y generaltranslation@9.5.2 añaden el descubrimiento de Projects con paginación automática.

Comienza con la configuración guiada

Ejecuta gt init para configurar tu Project. Solo se inicia sesión cuando se crea un Project o una clave:

npx gt init

Usa gt login para iniciar sesión sin ejecutar la configuración inicial, o npx gt login --no-browser para aprobar el acceso desde otro dispositivo. En ambos casos se requiere la aprobación de una persona.

gt whoami muestra la identidad con la que has iniciado sesión y gt logout elimina la sesión guardada. Para flujos de trabajo desatendidos, usa API Keys con permisos restringidos guardadas en el almacén de secretos de tu proveedor de CI.

Ejecutar la configuración desde scripts y agentes

Cada pregunta de configuración tiene su propio flag. Sin una terminal, o con --no-interactive, gt init indica las opciones que faltan antes de modificar ningún archivo, y --json notifica los eventos de inicio de sesión, traspaso y resultado:

npx gt init --no-interactive --json --defaults --locales fr es --no-dev-credentials

--defaults acepta las opciones locales recomendadas, pero nunca crea Projects ni claves.

Elige un Project y los permisos de la clave

gt init puede seleccionar un Project al que tengas acceso o crear uno en una Organization en la que tengas permisos y, después, guardar su ID y una clave de runtime de desarrollo en .env.local.

La clave solo concede project:translations:generate: está pensada para traducciones en runtime locales, no para cargas desde la CLI ni para CI. Los valores existentes de GT_API_KEY no se modifican. Los Projects de Next.js con App Router reciben NEXT_PUBLIC_GT_PROJECT_ID y NEXT_PUBLIC_GT_DEV_API_KEY, de modo que los componentes cliente también se traducen en desarrollo; no incluyas ninguna de las dos en los builds de producción (consulta Credenciales de Next.js).

Usa gt api-key create si quieres crear una clave de Project adicional con los permisos que elijas:

npx gt api-key create --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate

Debes tener permiso para crear claves y otorgar cada uno de los permisos seleccionados. El comando muestra el secreto una sola vez; guárdalo en un lugar seguro. Para CI, elige permisos que cubran todo el flujo de trabajo en lugar de reutilizar este ejemplo, que solo permite generar. Nunca incluyas API Keys en los bundles desplegados para navegador o dispositivos móviles.

Usa llamadas tipadas a la API y comprueba los resultados de los jobs

Usa paginate de generaltranslation/api para recorrer todos los Projects a los que tiene acceso tu API Key sin tener que gestionar cursores:

import { listProjects, paginate } from 'generaltranslation/api';

for await (const project of paginate(listProjects, { client })) {
  console.log(project.id, project.name);
}

Con un cliente createApiClient, los fallos HTTP en las llamadas con throwOnError ahora lanzan un ApiError con el código de estado HTTP en code.

Los helpers de sondeo del cliente de la API te permiten esperar a que terminen los trabajos de traducción y devuelven complete: false si se agota el tiempo de espera. Que hayan terminado no significa que todos los trabajos se hayan completado correctamente. Comprueba los resultados de los trabajos antes de descargar las traducciones.

El formateo de diagnósticos ya está disponible desde el punto de entrada público generaltranslation/diagnostics. Las herramientas pueden formatear mensajes con indicaciones prácticas sin importar el punto de entrada completo de Core.

Actualización

Actualiza para poder listar Projects y Organizations. La API ahora los devuelve en items en lugar de projects u orgs, y rechaza los cursores emitidos antes de este cambio. Las versiones anteriores de la CLI no pueden listarlos en gt init. Quienes llamen directamente por HTTP o a través del SDK deben leer items y reiniciar la paginación.
Captura ApiError en las llamadas que lanzan excepciones. Los fallos HTTP en las llamadas con throwOnError y en awaitJobs lanzan ApiError en lugar del cuerpo de respuesta decodificado. Las llamadas sin throwOnError siguen devolviendo el cuerpo en error.
Mueve src/gt.config.json. La CLI ya no lo lee. Muévelo a la raíz del Project o pasa --config src/gt.config.json.
Reemplaza gt auth y --key-type. Usa login para autenticar tu cuenta, init para configurar el Project de forma guiada y la creación explícita de claves para obtener credenciales adicionales. gt configure no es un sustituto sin efectos secundarios: según tu configuración, puede instalar dependencias y aprovisionar credenciales.
Mantén separadas las credenciales de runtime y de herramientas. GT_DEV_API_KEY sigue siendo una opción de runtime del framework. Iniciar sesión no basta para configurar las credenciales del SDK en runtime. Las API Keys explícitas siguen teniendo prioridad sobre el inicio de sesión guardado de la CLI; consulta selección de credenciales.
Revisa lo que das por sentado sobre los reintentos. Las solicitudes POST de gestión no se reintentan automáticamente ante fallos de red o del servidor, aunque las respuestas 429 sí pueden reintentarse si los reintentos están habilitados. La traducción en runtime de Core no reintenta automáticamente ni estos fallos ni las respuestas 429. No repitas a ciegas la creación de Projects o claves: cada solicitud exitosa crea un recurso nuevo.
Conserva las API de compatibilidad admitidas. La alternativa devApiKey de Core y getProjectData siguen disponibles, pero están obsoletas. Usa apiKey y da preferencia a getProjectInfo en las nuevas llamadas para obtener información del Project.
Adapta tu código a los cambios de validación y de resultados. Los valores de proveedor de modelos no admitidos fallan antes de enviarse la solicitud. Los resultados de carga de fuentes ya no incluyen el campo deduped.