Units, segments, formats and kinds¶

Units¶

A unit is one translatable object on your site. Connectors choose its external_key, which must stay the same for the object’s whole lifetime and match ^[A-Za-z0-9_.:-]{1,255}$.

Adapter	Unit	Example `external_key`
`djangocms`	a django CMS page content in the source language	`djangocms:page:42`
`wagtail`	a Wagtail page	`wagtail:page:<translation_key>`
`parler`	a django-parler model instance	`parler:blog.post:17`
`modeltranslation`	a django-modeltranslation model instance	`modeltranslation:shop.product:3`

Segments¶

A segment is one translatable field value inside a unit. Its key must be stable and unique within the unit. Good keys identify what the text is, not where it is in a list:

Content	Example `key`
A model field	`title`, `meta_description`
A django CMS plugin field	`plugin:103:body`
A StreamField block	`body.<block uuid>.heading`

position and parent_key describe the structure, for example a plugin tree or nested blocks, so a connector can rebuild it in the target language. Changing them doesn’t make translations stale.

Formats¶

`format`	Use for	Whitespace in fingerprints	QA checks HTML
`plain`	Plain text (the default)	Line breaks count	No
`markdown`	Markdown	Line breaks count	No
`html`	HTML fragments, e.g. djangocms-text	Collapsed	Yes
`rich_text`	Rich text stored as HTML, e.g. Wagtail rich text	Collapsed	Yes

Results have the same format as their source segment.

Kinds¶

kind is a free-form hint of up to 50 characters. Ponyglot uses it in prompts and QA. These values have an effect:

`kind`	Effect
`meta_description`	SEO warning above 160 visible characters, unless the segment has `max_length`.
`meta_title`, `seo_title`, `page_title`	SEO warning above 60 visible characters, unless the segment has `max_length`.
`alt_text`	An empty translation is reported as an empty alt text.

Other common values are title, body and link_text. Send them anyway: they help the LLM choose the right register and length.

Lengths¶

Set max_length when the target field has a length limit, for example a CharField. A translation longer than that is a QA error and isn’t delivered.