Quillet
Menu
Menu

Locales and fallback

4 min read

A translation in Quillet holds only the fields it translates, and every field it leaves out is read from the project's default locale at the moment a reader asks for it.

Why a translation holds only what it translates

A translation that copies its source starts drifting the day it is made. Change a button label in English, and every copy still holds the old one. Add a field, and every copy is missing it, so the page shows a blank.

Quillet takes the other route. A German document starts empty and inherits everything. You translate it field by field, and each field you have not reached yet still reads as the English one, never as a blank. When the English changes, every field you did not translate changes with it. The same idea decides how a translation is checked: against what a reader would receive. That is why an empty translation of a component with a required field is accepted. The required field comes from the default locale.

How fallback fills a translation's gaps

The German answer is two fields of its own and three borrowed from en-US, and the response says which three.

How a read resolves

For a request in de-DE, delivery loads two versions: the published de-DE version and the published version in the default locale. What it does with them depends on the document's type.

  • A structured document is merged field by field. The requested locale wins wherever it has a value, and every absent field comes from the default locale. A list is replaced as a whole, never merged item by item.
  • A Markdown or plain-text document falls back as a whole, because prose cannot be merged sentence by sentence.
  • If neither version exists, the answer is a 404.

The answer says what happened. _meta.resolvedLocale is the locale that answered, _meta.fallbackLocale is the locale that filled gaps, and _meta.fallbacks lists the fields that came from it, or ["*"] when the whole document did.

A field marked not translated in its component is shared. It exists only in the default locale, and every locale reads it from there. It is never listed as a fallback, because it is not missing. A SKU or a price is the usual case.

Completeness and review are separate questions

Completeness asks which translatable fields still fall back, and it puts a locale in one of three states: missing, partial or translated. Review asks whether a person has read the translation against the current source. The two answers can differ. A translation can be complete and still need review, because the English changed after the German was checked. It can also be reviewed and still hold unpublished edits. The dashboard shows the three facts as three badges, so that no one of them hides another.

Mark reviewed records the two version numbers you were looking at. Any later change to the source's content flags the translation again.

How to

Dashboard

  1. Open a structured document in the default locale. In the page bar's locale switcher, choose a locale marked (not translated).
  2. Press Start the de-DE translation (the button names the locale you chose). The editor opens on an empty body, and the panel beside it lists every field inherited from en-US.
  3. Press one field in that list. It leaves the list and its English value is in the body. Translate it and press Save.
  4. In the Content tab, open View and choose Partial translations. The document is listed until every translatable field has its own value.

API

Read the translation through delivery after publishing it:

curl -s -u '<keyId>:<secret>' \
  'http://localhost:3000/d/v1/<project>/<env>/content/<key>?locale=de-DE'

In the answer, _meta.fallbacks names each field still read from the default locale.

Limits

  • There is one fallback locale, the project's default. A chain such as de-AT to de-DE to en-US is not supported.
  • Lists fall back whole, and a not-translated field inside a block list has no effect, because blocks are translated whole.
  • Blocks have no stable ids, so two locales cannot line up the items of one list.
  • Review is not field-aware. Any change to the source's content flags every translation of it, and that includes a restore.
  • Completeness and review are measured on drafts, not on what is published.
  • Locales come from a fixed catalogue of language and region pairs, such as en-US. A bare en is refused, and a locale that still has documents cannot be removed from the project.

Last updated