Control and review¶
Nothing is published automatically. This is Ponyglot’s central promise, and it shapes how translations travel from Ponyglot to your site.
Drafts and suggestions¶
Ponyglot never writes to your site. The connector on your site fetches translations and stores them in a way that needs an editor’s approval:
django CMS and Wagtail content lands as drafts, using the CMS’s own versioning.
Model content (django-parler, django-modeltranslation) has no versioning, so it lands as suggestions with a diff. Editors apply them in the admin.
Editors approve in the tools they already use. They can change a translation before approving it; the connector reports the final text to Ponyglot, and the translation memory learns from it. This applies to every translation, including exact matches from the translation memory.
Why the connector pulls¶
Many websites sit behind firewalls or run in environments that don’t accept incoming connections. So the connector starts every exchange: it pushes content and pulls results. No one needs to open a port, and Ponyglot needs no credentials for your site.
At-least-once delivery¶
A connector fetches results, writes drafts, and then acknowledges them. Until Ponyglot receives the acknowledgement, it keeps offering the results. If the connector crashes after fetching but before writing, nothing is lost: the next pull delivers the same results again.
The price for this safety is that a result can arrive more than once. A connector must therefore write drafts idempotently: writing the same result twice must leave one draft.
Why result IDs change¶
Each result has an ID such as r_5012. It identifies one version of a translation, not
the segment. When Ponyglot produces a new version, for example because someone forced a
retranslation or fixed the text in the review queue, the new version gets a new ID, even if
the source text is the same.
This prevents an old decision from hitting a new text. Suppose an editor on the site rejects
an old draft while Ponyglot has already produced a better one. If both had the same ID, the
rejection would discard the new version the editor never saw. With version IDs, Ponyglot
recognises the review as belonging to a superseded version and ignores it (ignored in the
response). Acknowledgements work the same way.
For connectors, this means: store the ID with the draft, send back exactly that ID, and never build or parse IDs yourself.
Only current translations are delivered¶
If an editor changes the source while a translation is on its way, the translation no longer fits. Ponyglot stops offering it, and the next job translates the new source. Your editors never review a translation of text that no longer exists.
Where review happens¶
Two places, with a clear division:
The CMS or admin is where editors approve or reject delivered drafts. That’s the normal path for every translation.
Ponyglot’s review queue handles translations that failed QA checks and were never delivered. Once a translation has reached your site, Ponyglot no longer changes it; if the connector acknowledges a translation while someone edits it in the queue, the connector wins.