Setup guide: your own translation engine, step by step

One configuration that works end to end — the exact endpoint, the exact model, and the measurements behind the choice.

Google Translate works with no key at all, and if you only want to read the occasional page you can stop there. This guide is for the other case: you want translation good enough to read closely, plus the listening and speaking review that needs speech and transcription. That means bringing your own keys, and the whole point of doing so is that your text goes from your browser to that provider directly — there is no server of ours in between.

What this guide sets up

1. Install it and switch the extension on

Install from the App Store, or load the Chrome or Firefox build. Then switch the extension on once — on iPhone that happens in Settings, and belliedmonkey.cc/setup.html detects it and confirms when it is actually working.

2. Get an API key

Sign up at https://platform.deepseek.com and create an API key. Any of the supported providers works; this guide uses DeepSeek because it is inexpensive, fast enough for whole pages, and its key works from anywhere.

3. Enter the key and press Test connection

Open the extension's Settings, choose DeepSeek as the translation engine, paste the key, and press Test connection. The endpoint and model are filled in for you — https://api.deepseek.com/v1/chat/completions with model deepseek-v4-flash — and you only change them if you are pointing at a gateway or a different model.

4. Read-aloud

The device's built-in voice is free, works offline and needs no key, which is the right default. If you want a better voice for listening practice, OpenAI Speech takes a key of its own at https://api.openai.com/v1/audio/speech with model gpt-4o-mini-tts.

5. Transcription, for the speaking exercises

Speaking review needs to hear you, which means a transcription endpoint. OpenAI Transcribe uses https://api.openai.com/v1/audio/transcriptions with model whisper-1 and the same kind of key. If you would rather nothing left your machine, point it at a local server instead — the field takes any endpoint speaking the same shape.

6. Translate one page to confirm

Open a page in a language you do not read, switch translation on, and check that each paragraph keeps its original with the translation underneath. If a paragraph fails it now says so with a retry you can press, rather than sitting at "Translating…".

Why this engine, and why you do not have to tune it

Reasoning models are the trap here. Left alone, DeepSeek's deepseek-v4-flash spends tokens thinking about every single paragraph: measured on 2026-08-20, one paragraph took 3549 ms and burned 278 thinking tokens. With thinking switched off the same paragraph came back in 1126 ms — 3.2× faster for text that reads the same.

The extension sends that parameter for you, per host and per model, from a table built out of measurements rather than documentation. The reason it has to be measured is that documentation does not predict it: on another provider the identical situation cost 24833 ms before and 1410 ms after — 17.6× — and on a third, sending the documented parameter returns HTTP 200 with an empty body, which looks like a bug in the extension and is not.

A host the table has never seen gets the protocol minimum and nothing else, which is why a gateway inside your own company works on the first try instead of failing on a parameter it does not implement.

Every engine, with its exact address

These are read from the same registry the software ships with, so this table cannot drift away from what the app actually does.

Anything else that speaks one of the two request shapes works too — you supply the whole address yourself:

When something does not work

The key is rejected but you are sure it is right

Several providers issue region-bound keys and run separate hosts for them, so a key from one console will not authenticate against the other's address. Check that the endpoint's domain matches the console you created the key in.

Nothing happens and there is no error

A request that returns HTTP 200 with an empty body is almost always a reasoning model that spent its whole output budget thinking. The extension avoids this for the models it knows; if you switched to a model by hand, switch back or reduce it to a non-reasoning one.

It works in one browser but not another

Settings live on the device and are not shared unless you turn sync on, so a key entered on a Mac is not on the phone. Enter it again there, or sign in and let sync carry it.

See also: frequently asked questions · YouTube dual subtitles · Safari on iPhone