Guides
Studio
Your JSON catalogs are the database and git is the history. Studio is a window onto them, which is why it cannot drift from your code: it does not own anything.
Run it
pnpm add -D @verbaly/studioIt prints the address it is serving, the project it read and what is in it. The address carries a key that is minted fresh every time it starts, so nothing else on your machine can talk to it by guessing the port.
The command
| Flag | What it does |
|---|---|
--root <path> | Point at another project instead of the folder you are in |
--port <n> | Start somewhere other than 4747; a busy port climbs to the next free one |
--json | Print the whole state and exit, no server. This is the panel without the panel: the same object the screen will read, so you can pipe it, diff it and script it |
It never edits your source text
Your source text lives in your code and the key is derived from it, so writing over it here would be undone the next time you extract. Saving into your source language is refused, and so is a key your source catalog does not have, because accepting one would invent a message no line of your code asks for.
A translation you save runs the same two checks verbaly check runs in your build, so a lost {name}, a lost tag or a plural missing its catch-all case is refused with the reason. Saving is also accepting: a translation a person wrote stops counting as a machine draft in the same breath.
The addresses
Every one of them calls the same function the CLI calls, so there is no second implementation to keep in step. Every answer is JSON, errors included.
| Address | What it gives you |
|---|---|
GET /api/state | The whole project in one answer: your settings, every catalog, where each message is used, the coverage, what the build gate says, the machine drafts, the triage and anything it could not read |
GET /api/health | The same diagnosis verbaly doctor prints |
PUT /api/message/:locale/:key | Write one translation and stop counting it as a draft |
POST /api/approve | Accept machine drafts: a list of keys, or the whole language at once |
The state comes in one piece on purpose. The biggest project we know is 1479 messages in three languages, and on your own machine that answers in under a third of a second.
Nothing it reads can take it down
A catalog it cannot read, a drafts file it cannot read, a source file that will not compile, or a folder with no catalogs in it are each reported by name, next to the rest of the state, and everything else still loads. This is not politeness: Studio is what you open to fix those files, so refusing to open would be the one behaviour that makes it useless.
Which machine translations to read first
Adding a language writes hundreds of drafts at once, and reading them one by one is a wall. Walls are how a safeguard turns into something people route around, so Studio ranks instead of queuing. The build gate already caught the structure, so what is left is meaning, which nothing can measure. These do not score a translation, they point at the few worth your eyes.
| Signal | What it means |
|---|---|
divergent | A language you already reviewed wrote this same source text two different ways, so the source itself is ambiguous |
collision | The same doubt seen in the result, when no reviewed language can settle it |
echo | Still word for word the source, while every language with an opinion did translate it |
digits | A number the source has came back changed, ignoring the comma or dot a language writes differently |
url | A link changed |
code | What is inside a code span changed |
Every signal was measured against this site before it shipped, and two of them changed because of what the measurement said. On 1479 real messages, digits was reading the comma after a number as part of it, and it was flagging a number a translation added where the source had none, which is what "survives a refresh" becoming "sobrevive al F5" looks like. That was every single one of its hits, all of them correct text. Both are gone. The result is 18 messages out of 1479 flagged per language.
It writes files, so it defends itself
Any page open in your browser can talk to a server running on your machine, so three defences are on and cannot be turned off: it listens only on your own machine and never on the network; it refuses a request that claims to come from anywhere else, which is what stops a site from pointing its own name at your machine; and the key it mints at startup is compared in a way that cannot be guessed one character at a time. Requests are capped, and the full path of your project is stripped out of every error before the browser sees it.