Complete beginner reference for the DevSpeak Translation Editor. Documents every control: the Web Search, Output (Prose/XML), Model, and Project feature-bar controls; the Target Audience, Tech Context, Output Format, and Tone parameters; the Optimize, Translate Text, Fast AI, and Stop Generation actions; the attachments drawer (PNG, JPG, WEBP, PDF, TXT, MD, with per-file and per-request size limits); the Preview, Split, and Source output modes; the Iterate & Refine panel; and the command palette — with defaults and required subscription tiers.
Every Control in the Translation Editor
The Translation Editor is where most DevSpeak work happens. It looks like a
two-pane text editor, but almost every surface around those panes changes what
the model receives — sometimes dramatically. A tone slider moved four points
can turn a one-paragraph rewrite into a twelve-section specification.
This tutorial walks the interface control by control. For each one you get what
it does, what its default is, and a concrete reason to change it.
What You'll Learn
Prerequisites
Time Estimate
~12 minutes
Step 1 — Orient Yourself in the Header and Sidebar
The header holds navigation and account controls, not translation controls.
Left to right: the Translation Editor title, a save-status pill that cycles
through _Unsaved_, _Saving…_, _Saved_, and _Save failed_, links to
Dashboard and Docs, a language switcher that toggles EN / ES,
and your avatar menu.
The avatar menu holds three items: Account Settings, a Light Mode /
Dark Mode toggle that persists across sessions, and Sign Out.
The left sidebar switches workspaces. It collapses to an icon rail with the
chevron at its base.
| Sidebar item | What it opens | Tier required |
| ------------------- | --------------------------------------------------- | --------------------------------------------------------- |
| Translate Text | This editor | FREE |
| Translate Files | Batch document translation jobs | VIBECODER |
| Projects | Context Projects — reusable instructions and assets | VIBECODER |
| History | Your saved translations | FREE |
| Notes | The Notes workspace | ENTERPRISE |
| API Keys | Public API key management | Every plan (FREE and VIBECODER: 1 key, 50 requests/month) |
API Keys is a shortcut. The canonical place to create and manage your API
keys, and to connect your own provider key, is
Account Settings → Keys & Providers.
Locked items stay visible with a PRO badge. Clicking one opens the pricing
modal rather than failing silently — that is deliberate, so you can see what
exists before you pay for it.
Below the navigation sits a System Status terminal that streams a live log
of what the editor is doing. It is the fastest way to tell a slow generation
apart from a stalled one.
Step 2 — Set the Feature Bar
The feature bar is the row directly above the four parameters. These four
controls change _how_ the request is executed rather than _what_ the document
says. All four are disabled while a generation is in flight.
Web Search is an on/off toggle, off by default. When on, DevSpeak
retrieves live web results and grounds the next generation on them. Turn it on
when the request depends on something that changed recently — a library's
current major version, a newly published RFC, a pricing page. Leave it off for
internal domain work, where retrieval adds latency and no accuracy.
Output is a two-option selector: Prose or XML. Prose is the
default and produces Markdown for humans. XML produces a deterministic,
machine-readable document — use it when a script, not a person, consumes the
result.
Model picks the model for the next generation. The default is **Auto
(recommended)**, which chooses a model for each request so you do not have to.
If you want a specific model, open the list and pin it; the list shows the
models available to your account, grouped by the company that built them.
The closed control shows the mark of the selected model's family next to the
Model label, so you can see at a glance who built the model you are about
to run. The marks do not appear inside the open list, because a native dropdown
cannot render icons in its options.
Your choice persists across sessions. If you have connected your own provider
key in Account Settings → Keys & Providers, an extra Your Provider group
appears right after the Automatic group, ahead of the model groups.
Not every model reads images. If you plan to attach a screenshot or a diagram,
leave the selector on Auto or pin a model you know reads images — a pinned
model that cannot read images rejects the request outright rather than quietly
ignoring the attachment.
Project attaches a Context Project to the request, so its stored
instructions and assets are supplied as grounding without you re-uploading
anything. This control requires VIBECODER and only appears once you have
created at least one project — if you do not see it, that is why.
Step 3 — Set the Four Translation Parameters
These four controls shape the document itself. They are the ones worth getting
right.
Target Audience — default Senior Dev. Choose from _Junior Dev_, _Senior
Dev_, _Tech Lead_, _SRE_, and _Data Engineer_. This changes how much is
explained rather than what is covered. A Junior Dev spec defines terms and
spells out reasoning; a Tech Lead spec leads with tradeoffs and sequencing.
Tech Context — default Backend. Choose from _Backend_, _Frontend_,
_Mobile_, _Data/ML_, and _DevOps_. This is the control people confuse with
audience. Audience decides who reads it; context decides which layer it
discusses. The same login request produces a session and token-storage
discussion under Backend, and a component-state and redirect discussion under
Frontend.
Output Format — default Technical Spec. Seven options:
| Format | Use it when |
| ------------------ | --------------------------------------------------------------- |
| Technical Spec | You need one document describing the whole change |
| Jira Tickets | The work needs to be split into individually assignable items |
| API Design | The deliverable is endpoints, payloads, and status codes |
| RFC | The decision needs to be argued and reviewed before it is built |
| Data Model | The deliverable is entities, fields, and relationships |
| Prompt | The output will be fed to another AI system |
| Optimize | You want your text improved, not converted into a document |
Tone — a 0 to 100 slider, default 50, labelled _Concise_ at the left
and _Detailed_ at the right, with a live percentage readout.
Tone is not a smooth dial. There is a hard behavioural split at 50:
register, and returns something roughly the length of what you gave it. It
will not invent sections.
headings, acceptance criteria, and edge cases you never mentioned. The exact
number then controls how much detail lands in each section.
If a translation comes back looking like a lightly edited version of your
input, check this slider before you blame the model.
Checkpoint
Before running anything, confirm you can point at:
Step 4 — Write and Optimize Your Input
The left pane is headed Non-Technical Input. Its header strip carries a
Clear Fields link, a live Words counter, the Optimize button, an
undo, a copy, and a cut button for the input text, and a
⌘↵ to generate keyboard hint. The strip adapts to the pane's own width rather
than the browser window, so dragging the split divider narrower drops the
secondary items in order of importance and keeps Optimize, undo, copy, and
cut on one line.
The cut button (the scissors icon) does copy and clear in one step: it
writes the input to your clipboard and empties the box. If the browser refuses
clipboard access the text stays put, so a cut never loses work.
Once you have typed something, a small ✕ appears in the top-right corner of
the textarea. It empties the text box and nothing else, then puts the cursor
back so you can start again immediately. Clear Fields in the header is the
heavier action: it asks for confirmation and resets the whole workspace —
text, attachments, and the generated output. The Clear button in the
action cluster (Step 5) does the same thing. After any of these, the undo
button or ⌘Z restores the input text — attachments and the generated output
cannot be restored.
Type informally. That is the entire point of the product:
``text
We need users to be able to sign in with their Google account
instead of making another password. Should work on mobile too.
`
Optimize is a separate operation from translating — this is the single most
useful distinction in the editor. It rewrites your input in place: better
grammar, steadier tone, clearer phrasing, same meaning. It does not produce a
specification and it does not touch the output pane. Use it when your notes
were dictated, typed in a hurry, or written in your second language. Optimize
is available on every tier.
There is no hard character limit, but past roughly 10,000 characters DevSpeak
interrupts with a size warning and offers to summarize the input first. That
threshold exists because very long inputs dilute the instructions rather than
enrich them.
Attachments
The Attachments drawer sits under the textarea and is expanded by default.
Drop files onto it or click to browse. Supported formats are **PNG, JPG, WEBP,
PDF, TXT, and MD. Each file can be up to 10 MiB**, but a
single request can carry at most 10 files and about **3.1 MB of attachments
in total**. A few large files hit the total
before they hit the per-file limit, and DevSpeak then asks you to remove one.
Each staged file appears as a chip with its own remove button.
Attachments are context, not instructions. A PDF of the existing API contract
or a screenshot of the current screen gives the model the specifics your prose
leaves implicit. Remember the vision constraint from Step 2: an image only
helps if the selected model can read images.
Step 5 — Run the Translation
The action cluster sits to the right of the parameter row.
Translate Text is the primary action and runs the full translation. The
keyboard shortcut ⌘↵ (Ctrl+Enter on Windows and Linux) does the same thing
from inside the textarea. The circular arrow icon beside it re-runs the same
generation — useful after nudging a single parameter.
Fast AI is a toggle, not a button. With it on, the output pane becomes a
live copy-edit of your input: shortly after you stop typing, DevSpeak corrects
only the sentences you changed and underlines the changed words. Click a
corrected sentence for up to two alternatives, and press Use this text to
copy the result into the input. Fast AI does not write the spec: **Translate
Text** turns it off and runs the full translation. Above 20,000 characters it
pauses.
Stop Generation replaces Fast AI while a generation is running. It aborts
the request immediately.
Clear wipes the input, the attachments, and the result. It asks for
confirmation first, because only the input text can be restored afterward (with
undo); the attachments and the result cannot.
While the model works, the output pane shows a phased progress state, and the
footer tracks Latency in milliseconds and Status as _Processing_,
_Refining_, or _Idle_.
Step 6 — Read and Edit the Output
The right pane starts on Awaiting generation signal… and fills once the
translation lands. Its toolbar carries four things.
The format label echoes the Output Format you selected. The Syntax
indicator reports what actually came back — _Markdown_ or _XML_ — read from the
content itself rather than from your request, so it stays honest if the two
ever disagree.
The Preview / Split / Source segmented control switches how you read the
document. Preview renders it, Source opens a Markdown editor, and Split shows
both with synchronized scrolling. Preview is the default. In Source and
Split the document is directly editable, and a Markdown utility bar gives you
bold, italic, headings, lists, quotes, code blocks, tables, and a formatter.
XML output has no view toggle and no utility bar — it renders read-only with
syntax highlighting, because a machine-readable document should not be
hand-edited in place.
The copy icon copies the whole document to your clipboard.
Between the panes is a draggable divider. Drag it to favour whichever side you
are working in; the editor remembers the position. Below 768 px the panes stack
vertically and the divider becomes horizontal.
Step 7 — Refine Instead of Regenerating
The Iterate & Refine panel sits at the bottom of the output pane once a
result exists. This is the third and last stage of the pipeline, and it is the
one people skip.
Refinement edits the generated document, not your original input. Ask for a
change in plain language:
`text
Add a section covering what happens when a user already has a
password account with the same email address.
`
Press Enter to submit; Shift+Enter inserts a newline instead. Each round
returns a complete replacement document rather than a patch, so the result
stays internally consistent instead of accumulating bolted-on paragraphs.
Every round is snapshotted into a version history with a timestamp and a short
summary of what changed. Revert restores an earlier version — and saves
that as a new snapshot, so reverting never destroys a later round.
Refinement requires VIBECODER. The panel stays visible on the FREE tier
with a PRO badge over it, so you can see the workflow before you buy into
it. Monthly rounds are capped by tier: 25 on VIBECODER, 100 on DEVELOPER,
unlimited on ENTERPRISE.
Step 8 — Learn the Two Shortcuts Worth Knowing
Press ⌘K or ⌘P (Ctrl+K / Ctrl+P) to open the command palette. It
searches actions — Generate Translation, Copy Result — navigation targets, and,
when a Markdown result is open, the formatting commands. It is the fastest path
to anything in the editor without reaching for the mouse.
The other one you will use constantly is ⌘↵` to generate from inside the
textarea.
Finally, note what is _not_ in the editor: Custom Instructions live in
Account Settings → Profile, not here. They are standing preferences —
"always use TypeScript", "prefer functional composition" — applied to every
translation, up to 10,000 characters, and they require VIBECODER. The same
page holds your default Target Audience, Tech Context, Output Format, and
verbosity, which is what seeds the parameter row each time the editor loads.
Checkpoint
You should now be able to:
Troubleshooting
The output is shorter than my input
Tone is below 50, which puts DevSpeak in rewrite mode. Move it to 50 or above
for a full document.
The spec discusses the wrong layer of the stack
Change Tech Context, not Target Audience. Audience controls how much is
explained; context controls which layer is discussed.
The Project dropdown is missing from the feature bar
It requires VIBECODER _and_ at least one existing Context Project. Create one
from the Projects sidebar item and it will appear.
My attached screenshot seems to have been ignored
Check the Model control. Some models cannot read images. Switch the selector
back to Auto, or pin a model that reads images, and re-run.
The Refine panel is dimmed and shows a PRO badge
Iterative refinement requires VIBECODER. Clicking the panel opens the pricing
modal.
Corrections appear in the output pane while I type
Fast AI is on. Toggle it off in the action cluster to go back to translating.
Summary
You've learned how to:
Next Steps
[Your First Translation with DevSpeak](/tutorials/getting-started/your-first-translation)
[grounding translations on a Context Project](/tutorials/mcp/ground-translations-on-a-context-project)
[Automate with the CLI](/tutorials/api-and-cli/automate-with-the-cli)