Guías
Studio
Tus catálogos JSON son la base de datos y git es el historial. Studio es una ventana a ellos, y por eso no puede desincronizarse de tu código: no es dueño de nada.
Qué te llevas
Se abre por lo que te necesita. La primera pantalla lista lo que está esperando, una línea cada cosa: traducciones que rompen tu web, mensajes vacíos, borradores de máquina que nadie ha leído, claves que tu código llama y ningún catálogo define, y claves que solo tiene una traducción. Las tres primeras abren la tabla justo en esos mensajes; las dos últimas no tienen fila que abrir, así que nombran sus claves. Al lado te dice cuántas comprobaciones de doctor pasan, y los últimos commits que tocaron tu carpeta de catálogos. Esa ficha necesita un repositorio git; sin él, simplemente no está.
El buscador lee tu texto, nunca la clave. Busca en todos tus idiomas, no solo en los que marcaste, y cada resultado dice en cuál coincidió. Command K lo abre, las flechas mueven y enter te lleva a ese mensaje en la tabla.
La primera parte de una clave es su grupo: nav.home es de nav. El raíl lista cada grupo con cuántos mensajes tiene y cuántos siguen pendientes, y elegir uno estrecha la tabla. Una clave sin punto no tiene grupo, y Verbaly no se lo inventa.
La tabla tiene todos los mensajes de tu proyecto, en tantos idiomas como marques. Cada uno enseña su estado: listo, sin traducir, escrito por una máquina y sin leer, o roto. Lo arreglas en la propia fila, y la comprobación corre mientras escribes.
Dos comandos se lanzan desde la página. Buscar texto nuevo lee tu código y añade lo que tus catálogos no tienen. Traducir lo que falta llama a tu proveedor: te enseña cuántos mensajes y en qué idiomas antes de gastar nada, lo que vuelve se queda en borrador hasta que lo leas, y un mensaje que guardes mientras corre conserva tu texto.
Cada fila tiene su menú. Copia la clave, copia el texto original, empieza a editar sin salir de la tabla, enseña los ficheros que usan ese mensaje, y enseña el commit que lo cambió por última vez.
El commit sale del historial de tus catálogos, comparando lo que decía cada mensaje y no la línea en la que estaba. Añadir una clave reescribe la coma de la línea de arriba, así que preguntarle a git quién tocó una línea nombra el commit equivocado más veces de las que uno querría. Cuando no hay respuesta, el menú dice de qué tipo es: un mensaje que aún no has commiteado, uno más viejo que el historial que leyó, o un proyecto sin git dentro.
Arráncalo
pnpm add -D @verbaly/studioImprime la dirección que sirve, el proyecto que leyó y lo que hay dentro. La dirección lleva una clave, nueva en cada arranque, así que nada más de tu máquina llega a ella adivinando el puerto.
El comando
| Flag | Qué hace |
|---|---|
--root <path> | Apunta a otro proyecto en vez de a la carpeta en la que estás |
--port <n> | Arranca en otro sitio que no sea 4747; un puerto ocupado sube al siguiente libre |
--json | Imprime el estado entero y sale, sin servidor. Es el panel sin el panel: el mismo objeto que leerá la pantalla, así que puedes pasarlo por una tubería, compararlo y meterlo en un script |
Nunca toca tu texto fuente
Tu texto fuente vive en tu código, y la clave sale de ese texto. Escribir encima aquí lo desharía tu siguiente extract, así que Studio lo rechaza. También rechaza una clave que tu catálogo fuente no tenga: aceptarla inventaría un mensaje que ninguna línea de tu código pide.
Una traducción que guardas pasa las dos mismas comprobaciones que pasa tu build. Un {name} perdido, una etiqueta perdida o un plural sin su caso general se rechaza, con el motivo. Guardar también es aceptar: en cuanto lo escribe una persona, deja de contar como borrador de máquina.
Tu archivo conserva el orden que le diste. Guardar reescribe la línea que cambió, nunca el catálogo entero. Un grupo que ordenaste a mano sigue en ese orden y una clave nueva cae al final; un grupo que ya iba alfabético sigue ordenándose. El diff que revisas es la edición que hiciste.
Las direcciones
Todas llaman a la misma función que llama el CLI, así que no hay una segunda implementación que mantener a la par. Todas responden JSON, los errores incluidos.
| Dirección | Qué te da |
|---|---|
GET /api/state | El proyecto entero en una sola respuesta: tu configuración, cada catálogo, en qué parte se usa cada mensaje, la cobertura, lo que dice verbaly check, los borradores de máquina, el triaje y todo lo que no pudo leer |
GET /api/health | El mismo diagnóstico que imprime verbaly doctor |
GET /api/commit/:key | El commit que cambió ese mensaje por última vez, o cuál de los tres motivos hace que no haya ninguno |
PUT /api/message/:locale/:key | Escribe una traducción y deja de contarla como borrador |
POST /api/approve | Acepta borradores de máquina: una lista de keys, o el idioma entero de golpe |
POST /api/extract | Lee tu código y añade lo que tus catálogos no tienen. Responde dentro de la propia petición, porque es local y no cuesta nada |
GET /api/translate | El presupuesto: cuántos mensajes y de qué idiomas, sin llamar a tu proveedor. Mirar el coste no puede empezar el gasto, y por eso es su propia dirección |
POST /api/translate | Arranca la tirada y te devuelve un trabajo. De uno en uno, porque dos tiradas sobre los mismos catálogos son una carrera por los mismos ficheros |
GET /api/job/:id | Cómo va esa tirada, para preguntarlo una vez por segundo |
GET /api/job | La tirada en curso, o nada. Una página recargada ha perdido el id, y un trabajo al que no puedes volver a preguntar es un stream con pasos de más |
El estado llega de una pieza, no por páginas. Incluso un catálogo de varios miles de mensajes en tres idiomas responde en una fracción de segundo en tu propia máquina.
Nada de lo que lee puede tumbarlo
Un catálogo que no puede leer, un archivo de borradores que no puede leer, un fuente que no compila, una carpeta sin catálogos dentro: cada uno se reporta por su nombre, y todo lo demás carga igual. Studio es lo que abres para arreglar esos archivos, así que tiene que abrir.
Qué traducciones automáticas leer primero
Añadir un idioma escribe cientos de borradores de golpe. Leerlos uno a uno es como la gente acaba saltándose la revisión entera, así que Studio los ordena en vez de ponerlos en cola. Tu build ya cazó la estructura; lo que queda es el significado. Estas señales no puntúan una traducción, señalan las pocas que merecen tus ojos.
Marca un solo idioma y la tabla se vuelve ese idioma. Una barra encima dice cuántos mensajes tiene, que ya están en tu web y que la comprobación de tu build pasa. Tres chips los reparten en todo, merece un vistazo y nada raro. Cada fila marcada lleva su motivo al lado: qué enlace cambió, qué número se movió. Marca un segundo idioma y vuelve la tabla comparativa, porque un motivo es de un idioma y no de una fila.
| Señal | Qué significa |
|---|---|
divergent | Un idioma que ya revisaste escribió este mismo texto fuente de dos formas distintas, así que el fuente es ambiguo |
collision | La misma duda vista en el resultado, cuando ningún idioma revisado puede zanjarla |
echo | Sigue palabra por palabra igual que el fuente, mientras todos los idiomas con opinión sí lo tradujeron |
digits | Un número que el fuente tiene volvió cambiado, ignorando la coma o el punto que cada idioma escribe distinto |
url | Un enlace cambió |
code | Lo que hay dentro de un span de código cambió |
Las señales se afinaron contra traducciones reales, no se inventaron en una mesa. Dos se cayeron, porque todo lo que marcaban resultó ser texto correcto. Lo que queda es una lista corta, no una cola.
Escribe ficheros, así que se defiende
Cualquier página abierta en tu navegador puede hablar con un servidor de tu máquina, así que van tres defensas puestas y no se pueden quitar.
- Escucha solo en tu propia máquina, nunca en la red.
- Rechaza una petición que dice venir de otro sitio, que es lo que impide que una web apunte su propio nombre a tu máquina.
- La clave que crea al arrancar se compara entera, así que no se puede adivinar carácter a carácter.
Las peticiones tienen tope, y la ruta completa de tu proyecto se quita de cada error antes de que el navegador la vea.