Pull results and report reviews¶

This guide shows how a connector receives translations, writes them as drafts, acknowledges them, and reports what editors decided. Ponyglot never writes to your site: the connector pulls.

Pull ready results¶

Call GET /v1/results. Each page has up to limit results (default 100, at most 500):

{
  "results": [
    {
      "id": "r_5012",
      "unit": "djangocms:page:42",
      "key": "plugin:103:body",
      "language": "de",
      "text": "<p>79 € pro Site und Monat</p>",
      "format": "html",
      "source_fingerprint": "9f2c5a0e0c1b4d8e7a6f3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e",
      "origin": "deepl",
      "engine": "deepl",
      "job_id": 17,
      "qa": []
    }
  ],
  "next_cursor": "MjAyNi0wOS0yNFQxMDowMDowMCswMDowMHw1MDEy"
}

While next_cursor isn’t null, request the next page with ?cursor=<next_cursor>. Store the last cursor only for the current run: results that you don’t acknowledge are listed again in the next run anyway.

Poll on a schedule that suits your site, for example every few minutes while a job is active.

Write drafts¶

For every result, write text to the target language as a draft (django CMS, Wagtail) or a suggestion (models). Never publish it.

Store the result id with the draft. Reviews refer to it. Treat it as an opaque string: don’t parse it, and don’t replace it with your own IDs.
Make writing idempotent. Delivery is at least once: after a crash, you may receive the same result again. Writing the same draft twice must not create two drafts.
If a newer result arrives for the same segment and language, it replaces the earlier draft. The earlier result ID is then superseded.
Show the qa warnings to the editor next to the draft, for example {"code": "seo", "severity": "warning", "message": "171 characters; search engines show about 160."}.

Results only ever cover the current source text. If the source changed after translation, the result is not listed and the next job translates the segment again.

Acknowledge¶

After writing the drafts, acknowledge their IDs with POST /v1/results/ack:

{"ids": ["r_5012", "r_5013"]}

The answer tells you how many were acknowledged: {"acknowledged": 2}. Acknowledged results leave /results and count as in review. Acknowledging a superseded or unknown ID does nothing, so repeating an acknowledgement is safe. Send up to 1,000 IDs per request.

Report reviews¶

When an editor approves or rejects a draft on the site, report it with POST /v1/reviews:

{
  "reviews": [
    {"id": "r_5012", "outcome": "approved", "text": "<p>79 € pro Website und Monat</p>",
     "reviewer": "anna"},
    {"id": "r_5013", "outcome": "rejected"}
  ]
}

Approved without changes: leave out text.
Approved with changes: send the final text as published in text. Ponyglot stores it as a human translation and adds it to the translation memory, so the correction is reused.
Rejected: the segment counts as missing again. The next delta job translates it.
reviewer is optional, for example the editor’s username.

The answer lists what happened:

{"updated": 1, "ignored": ["r_5013"]}

ignored contains IDs that were unknown, superseded, or not waiting for review. A typical reason: the editor reviewed an old draft after a newer result replaced it. Send up to 500 reviews per request.

When result IDs change¶

A result ID identifies one generated version of a translation. A new version gets a new ID, also when the source text is the same, for example after a forced retranslation or after an editor fixed the translation in the review queue. Ponyglot then lists the new version in /results, and reviews of the old ID are ignored. Always review the ID of the draft the editor actually saw.