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
Una página con todos los mensajes de tu proyecto, en los idiomas que marques, y el estado de cada uno: listo, falta, lo escribió una máquina y nadie lo ha leído, o rompe tu web. Corriges uno en la propia fila donde vive, y la validación corre mientras escribes.
Desde la página corren dos comandos. 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, así que te enseña cuántos mensajes y de qué idiomas antes de gastar nada, y lo que vuelve se queda en borrador hasta que lo hayas leído.
Arráncalo
pnpm add -D @verbaly/studioImprime la dirección que está sirviendo, el proyecto que leyó y lo que hay dentro. La dirección lleva una clave que se acuña nueva cada vez que arranca, así que nada más en tu máquina puede hablarle 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 key sale de él, así que escribir encima aquí se desharía la próxima vez que extraigas. Guardar en tu idioma fuente se rechaza, y también una key que tu catálogo fuente no tiene, porque 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 verbaly check en tu build, así que un {name} perdido, una etiqueta perdida o un plural sin su caso general se rechaza con el motivo. Guardar también es aceptar: una traducción que escribió una persona deja de contar como borrador de máquina en el mismo gesto.
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 el gate del build, 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 |
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 viene de una pieza a propósito. El proyecto más grande que conocemos son 1587 mensajes en tres idiomas, y en tu propia máquina eso responde en menos de un tercio de segundo.
Nada de lo que lee puede tumbarlo
Un catálogo que no puede leer, un fichero de borradores que no puede leer, un fichero de código que no compila, o una carpeta sin catálogos dentro se avisan por su nombre, junto al resto del estado, y todo lo demás carga igual. Esto no es cortesía: Studio es lo que abres para arreglar esos ficheros, así que negarse a abrir sería justo lo que lo hace inútil.
Qué traducciones automáticas leer primero
Añadir un idioma escribe cientos de borradores de golpe, y leerlos uno a uno es un muro. Los muros son la forma en que un salvavidas se convierte en algo que la gente esquiva, así que Studio ordena en vez de hacer cola. El gate del build ya cazó la estructura, así que lo que queda es el significado, que no hay forma de medir. Estas señales no puntúan una traducción, señalan las pocas que merecen tus ojos.
| 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ó |
Cada señal se midió contra este sitio antes de publicarse, y dos cambiaron por lo que dijo la medición. Sobre 1479 mensajes reales, digits leía la coma que sigue a un número como parte de él, y marcaba un número que la traducción añadía donde el fuente no tenía ninguno, que es justo lo que pasa cuando "survives a refresh" se traduce como "sobrevive al F5". Eso era absolutamente todo lo que marcaba, y todo era texto correcto. Las dos cosas están fuera. El resultado son 18 mensajes de 1479 marcados por idioma.
Escribe ficheros, así que se defiende
Cualquier página abierta en tu navegador puede hablar con un servidor que corre en tu máquina, así que hay tres defensas encendidas que no se pueden apagar: solo escucha en tu propia máquina y 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; y la clave que acuña al arrancar se compara de una forma 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 la vea el navegador.