How the connectors work¶

A connector sits between your Django site and Ponyglot. It decides what is translatable, sends it as units and segments, and writes translations back in a way your editors control. This page explains what it sends, when, and how translations come back.

Saving never waits for Ponyglot¶

When an editor saves or publishes content, the connector only notes that the object changed. It contacts Ponyglot later, in ponyglot sync (see Run the sync). Your site stays fast and keeps working when Ponyglot or the network is unavailable; changes simply wait for the next sync round.

Each sync sends complete snapshots of the changed objects, reports what editors decided and fetches finished translations. Ponyglot tracks each translatable field or text block, called a segment. Changing a page’s meta description makes that field outdated; its unchanged title and plugin texts keep their translations. A rich-text field can contain several sentences: editing one sentence makes that whole field eligible for translation again.

What is sent¶

Models translated with django-parler or django-modeltranslation: every registered model, with its text fields. Slugs, URLs, email addresses and fields with choices aren’t sent. Each object is one unit.

django CMS: every model registered for frontend editing (cms_toolbar_enabled_models), such as pages, blog posts, aliases and your own content models. A unit is the content’s grouper: the page, the post. It contains:

the content model fields: for pages, title, menu title, page title and meta description;
the plugin fields, read from each plugin’s form as editors see it: plain text fields and rich text (as HTML). Fields for URLs, slugs, emails, choices, links and attributes, hidden fields and fields named like identifiers, code, CSS classes, icons or anchors are left out.

This covers djangocms-frontend, whose texts live in a JSON field: they are read and written in place, while code blocks, heading ids and link targets are left alone. Links inside rich text are translated as part of their sentence.

You can narrow all of this down: see Keep content out of translation.

Stable keys for plugins¶

django CMS gives plugins new ids with every version. The connector therefore gives each plugin its own key that follows it across versions and languages; a translated plugin shares the key of its source plugin. That’s how Ponyglot recognises the same text after you publish a new version. For a site that is already translated, plugins are matched by their place in the tree (placeholder, plugin type, position) on the first sync, and their existing texts are imported.

How translations come back¶

Nothing is published automatically (see Control and review). How a translation arrives depends on what your content can hold:

Content	Arrives as	Approved by
django CMS content with djangocms-versioning	a draft in the target language	publishing it
django CMS content without versioning	nothing is written; the translations wait in the dialog	choosing Apply (publishes)
Wagtail content with wagtail-localize	a draft revision	publishing it in Wagtail
parler and modeltranslation models	suggestions next to the fields in the admin	applying them

django CMS drafts¶

A unit arrives in one piece per language.
A draft the connector wrote and nobody touched since is updated with newer translations.
If the language is published, a new draft is created; only changed texts are updated, so earlier corrections stay.
A draft someone edited is never overwritten. The translations wait, and Apply to draft writes them when you choose.
Plugins added to the source are added to the translations at the same place, with their children. Nothing is removed or moved.

Content types differ in how they store languages:

	One content object per language	All languages in one content object
Examples	pages, posts, aliases	custom models whose plugins carry their language
Sent	content model fields and plugin fields	plugin fields
Translation arrives in	a draft of that language’s content (created if missing)	the target-language plugins in the object’s draft
Published	per language	all languages together

Suggestions for models¶

A suggestion holds the translation until an editor applies or rejects it in the admin. A suggestion whose source changed in the meantime can’t be applied; it is translated again.

Decisions flow back¶

The next sync reports what editors did: published drafts and applied suggestions count as approved, including the editors’ corrections, which go into your translation memory. Discarding or archiving a delivered draft, or rejecting a suggestion, counts as rejected.

QA errors¶

Every translation passes Ponyglot’s quality checks. Depending on your plan and site settings, a translation with errors either arrives with the error shown, for editors to fix, or waits in Ponyglot’s review queue until a reviewer resolves it. The connector’s dialogs show which applies, and link to the review queue.

Translated slugs¶

Slugs aren’t sent for translation. When a translated title is applied, the connector sets the slug in that language with slugify, unique per language and within the field’s length:

an empty slug is filled,
a slug that was derived from the old title follows the new one,
a slug written by hand stays.

Your views must find objects by the slug of the active language, for example with django-parler’s TranslatableSlugMixin under i18n_patterns. When a slug follows a changed title, the old URL in that language stops working unless you add a redirect. To keep a model’s slugs out of this, list them in EXCLUDE_FIELDS; to follow a different field than the title, use SLUG_SOURCES (see Connector settings).

Writing your own connector¶

Everything the connectors do goes through the public API. For content the connectors don’t cover, you can add your own adapter to the ponyglot core (Build a custom adapter) or connect another system directly (Connect a site through the API).