Install and configure a connector¶

This guide shows how to install the Ponyglot connector on a Django site, connect it to your site in Ponyglot, and send your existing content. The dashboard’s Getting started shows the same steps with your API key filled in (see Translate your first django CMS page).

Before you start¶

Python 3.10+ and Django 5.2+. For django CMS: django CMS 5.1+; djangocms-versioning 2.7+ is recommended, because without it translations can’t arrive as drafts.
A site in Ponyglot with its source and target languages, and an API key for this site (the site’s page › API keys; you need the admin or owner role).
Your translation library must already be configured for those languages. For Wagtail, this includes wagtail-localize; for modeltranslation, the target-language database columns must exist.

Need an account? During early access, request an invitation. The packages below install from PyPI. You can complete this guide before subscribing; requesting hosted translations needs a subscription that covers the site.

Install the packages¶

Install the package for each kind of content you translate:

Your content	Install	Add to `INSTALLED_APPS`
django CMS pages and other frontend-editable content	`pip install "djangocms-ponyglot[versioning]"`	`"ponyglot"`, `"djangocms_ponyglot"`
Wagtail pages with wagtail-localize	`pip install wagtail-ponyglot`	`"ponyglot"`, `"wagtail_ponyglot"`
Models translated with django-parler	`pip install "ponyglot[parler]"`	`"ponyglot"`, `"ponyglot.contrib.parler"`
Models translated with django-modeltranslation	`pip install "ponyglot[modeltranslation]"`	`"ponyglot"`, `"ponyglot.contrib.modeltranslation"`

Combine them as your site needs, for example django CMS pages and parler models:

INSTALLED_APPS += [
    "ponyglot",
    "djangocms_ponyglot",
    "ponyglot.contrib.parler",
]

Configure¶

Put the API key in an environment variable, never in version control, and add the PONYGLOT setting:

import os

PONYGLOT = {
    "API_KEY": os.environ["PONYGLOT_API_KEY"],
    "SOURCE_LANGUAGE": "en",  # default: LANGUAGE_CODE
}

Set PONYGLOT_API_KEY through your deployment’s environment settings, and make it available to management commands and the sync worker too. If your project loads a .env file, you can store it there; Django doesn’t load .env files by itself.

The languages come from Django’s LANGUAGES. Ponyglot translates into a target language only if your site can store it and it is a target language of the site in Ponyglot. All other settings are optional; see Connector settings.

Every environment that syncs needs its own site in Ponyglot and a key issued for that site. For a staging or preview environment, Set up a staging site: choose its production site under Staging site of. It shares production’s allowance without taking another site slot, and its approvals don’t teach the shared memory. Multiple keys issued for one site share that site’s content and results; use them for key rotation, not environment separation.

Check the connection¶

$ python manage.py migrate
$ python manage.py ponyglot check

check prints the API URL, the installed adapters and the languages, then introduces your site to Ponyglot. It ends with Connected to site “…” and the writable target languages. Warnings, such as a target language your site doesn’t have in LANGUAGES, are printed with !. Fix them in your settings or in the site’s settings in the dashboard.

Verify that the name is the site you intend to connect before sending content. If it names another site, correct PONYGLOT_API_KEY and run the check again.

Send your existing content¶

To see first how much content there is, count it without sending anything:

$ python manage.py ponyglot backfill --dry-run

Then send it:

$ python manage.py ponyglot backfill

This sends every translatable object once. Nothing is translated yet. Translations that already exist on your site are imported as approved, so they aren’t translated again and they fill your translation memory. With django CMS, only published content is sent.

Run backfill again after installing a new adapter or adding a translatable model. Limit it with --adapter, for example --adapter parler.

Keep it in sync¶

From now on the connector must sync regularly, so changes reach Ponyglot and translations come back. Set it up next: Run the sync.

Add the dialogs to your model admins¶

django CMS needs nothing more: the Ponyglot translations entry is in the toolbar’s Language menu. For parler and modeltranslation models, add PonyglotAdminMixin to their admins (see Add translation controls to the model admin).