A first draft in the other language
Since 1.9 a post can have a text in a second language, and every one of those texts was written by hand. Pavel asked for a machine to write the first one (#68) and sent a script that did it (#69). 1.12 makes that a command of the engine:
./blog.sh translate my-post --lang de --auto
The question it answers is not "can a machine translate my post". It can, more or less. The question is whether it can do so without anything reaching the site that nobody has read. That is what most of this release is about.
Nothing is saved by it
The translation is written to tmp/my-post.de.md and nothing else happens. You read the file, mend what needs mending, and save it:
./blog.sh add tmp/my-post.de.md
That is the same door a text sent from an app comes through. If the post changed while you were reading, the save is refused instead of writing over the change. Without a slug the command takes the newest published post; --force replaces a language that is already written.
In the wizard it is one key. A language with nothing written yet asks before the editor opens:
Translate it automatically? [a] automatically [Enter] write it yourself [Esc] back
[a] opens the editor on the machine's text, with the original and whatever looked wrong in the translation as // notes, which are dropped on save, as always.
You name the translator
The engine does not know whose model answers. It is a setting in env.sh, never in config/site.yml, because that file travels with the site's content and must not be able to name a program the engine runs. There are three kinds:
- A program of your own. Anything that reads the post on standard input and writes the translation to standard output:
claude -p,ollama run mistral, a script. - A model over the web.
TRANSLATOR=openai(and everything that speaks its API: Mistral, OpenRouter, Ollama, LM Studio),anthropicorgemini, with a model and a key. - A translation service.
TRANSLATOR=deeplorTRANSLATOR=libretranslate, which take no instructions and no model.
You do not have to write any of it by hand. ./setup.sh --translator asks about the translator and nothing else, writes env.sh and never shows the key. ./blog.sh doctor says whether what is set is whole.
DeepL and LibreTranslate translate text, not instructions, so they do not get the post whole. It goes paragraph by paragraph, each heading, list item and line of a quote on its own. Code, addresses, HTML and the marks of Markdown are kept aside as tags the service is told to leave alone, and a code block is not sent at all. The price of the pieces: a sentence that runs over a line break comes back as two.
What it checks, and what it does not
Before the file is written, the translation is compared with the original in the things a translator is known to damage and a reader does not notice: web addresses, the names of pictures, the numbers, and the count of headings and paragraphs. A difference is a warning, not a refusal, because a number may be written out in words for a good reason. An empty answer, one that ran out of room, or one the model declined is not saved at all. The slug: line is always left empty, whatever the model wrote there, so the address is made from the translated title, unless you write one yourself.
It does not check grammar. One small model translated a short text correctly and still put a Czech noun in the wrong case: "Druhý odstavce". No comparison of addresses and numbers catches that. Try a model on a post you can judge before you trust it with the rest.
When a provider refuses, you are told what it refused: a key that is wrong, an account with no credit, a model the plan leaves out. A code and one sentence, not an HTTP status.
In the apps
The Android and desktop apps have a Translate automatically button on the translation screen since 0.10.0. The iOS app has it too, and will bring it along once it reaches the App Store. The apps do not carry a key and do not translate anything themselves: they ask the server, the server runs the same command, and the text comes back with its warnings to be read and saved like a hand-written one. The button appears only where the server has a translator set up.
Who pays and where the text goes
A translation is paid for by someone and sent to someone, and the engine says so instead of hiding it:
- The text goes to the translator. A web service, or a model on your own machine. Free plans of some providers train their models on what they are sent; read the terms of the one you pick.
- The key stays on the server. It goes over https, or over http only to the same machine. It never appears in what the engine says, even when a provider repeats it back. A program of your own does not get the engine's other secrets from
env.sh. - A paired device may ask. That is the default, because the apps are where most of the writing happens. It also means a lost phone can have translations made at your cost until its key is revoked with
./blog.sh pair --revoke. A server that does not want that writesTRANSLATOR_REMOTE=denyinenv.sh, and the apps show no button.
What it is not
It is not a way to publish in two languages without writing in the second one. The engine stops at a draft on purpose: a machine translation nobody has read is not something to put on a site. What it takes away is the blank page. You correct a text instead of writing it, and the corrections are yours.
Comments