AI translation

The AI features run on the site owner's own Anthropic API key: bring your own key. Set it, and editors get:

• ✨ Translate on pages, articles, products and the other documents with drafts, and on the globals with text: the header, footer, microcopy and site settings;
• Translation status, with "Translate the whole site";
• 🖊 Proofread, 💬 Copy desk and Proofread the site for the default language;
• Translate a file for Word, PowerPoint, Excel and InDesign files;
• the learning loop: 🚩 reports, corrections, Distill and evaluations.

The editor guide describes each of them.

Turn it on #

1. Create a key in the Anthropic Console (console.anthropic.com).
2. Set ANTHROPIC_API_KEY in the site's environment and restart it.

The key is read when a call is made, never baked into a build. It stays on the server: it is never logged, sent to a browser or stored in the database.

Quality levels and models #

Editors choose a quality level, never a model. The models behind the levels are set in src/utilities/translate/anthropic.ts (TIERS):

The default level is set in the admin under Translation → Translation style guide ("Default quality"); without one it is Premium.

What it costs #

Anthropic bills the key's account for every call, at the price of the model used (anthropic.com/pricing). The kit has no price list of its own and no spending cap: set a limit for the key in the Anthropic Console if you want one. What drives the bill:

• The quality level. Standard costs about half of Premium; Fast is the cheapest.
• The review pass. After translating, a second reading by a native editor rewrites what reads as translated. It can cost as much again as the translation. It runs on marketing copy by default, never at Fast, and can be set to all text or off in the style guide.
• Translation memory saves calls. Approved translations are reused word for word, without the AI. A site that has been translated once costs far less to keep translated.
• The style guide and glossary are cached. They go with every call, and the API caches them, so repeated calls are cheaper. Changing the style guide makes the next calls a little slower and costlier while the new version is cached.
• Big runs show their size first. Proofread the site estimates the documents, characters and AI calls before it starts; Translate a file shows the paragraphs and how many approved memory already covers; an evaluation warns that it costs about as much as translating its reference texts twice.
• Busy periods do not fail at once. The API client retries rate limits and overloads up to six times, waiting in between.
• A public demo is capped. With DEMO_MODE, AI is off unless DEMO_AI_DAILY_LIMIT allows a number of calls a day. See Live demo.

What is sent to Anthropic: the texts being translated or proofread, with the style guide, the glossary decisions and the approved translations that apply to them, and for a document import, the documents themselves.

What is off without a key #

Without ANTHROPIC_API_KEY, every AI control is hidden and every AI endpoint answers 404. Nothing else changes: editors write, translate by hand and publish as before.

Background work #

Some AI work runs on the background jobs queue, so a page never waits for it: learning from a published translation, evaluations, Proofread the site and Translate a file. Make sure the jobs run where you deploy.

When something fails #

Errors from the AI service reach editors in plain words: a rate limit, an overloaded service, an exhausted credit balance or a rejected key ("A developer needs to check ANTHROPIC_API_KEY on the server"). A failed translation saves nothing.