Multilingual content

Decision of record: symmetric Paragraphs. One tree of parents and items is shared across languages. Copy lives in translatable paragraph fields. Structure (which parents exist, item order, width, color, placement, container JSON, trigger IDs, media) is language-neutral.

Paragraph translation cannot be scoped to one node type. Enabling it for International page enables it on every apb_* bundle. Other node types stay safe because their Content Translation setting remains off — no Translate tab on Basic page, Article, or the gallery. This docs site is English-only in v1 for the same isolation reason.

Field policy

Keep untranslatable_fields_hide=0 on APB hosts. If that Drupal setting is on, the Page Builder widget disappears on the translation form.

What works

• English, Spanish, and other translations of a node store the same paragraph IDs. Updating Spanish copy does not change English on the same ID.
• setNewRevision() on English copies existing translations onto the new revision.
• Cold language-prefixed overlay JSON is correct (entity converter + URL prefix).
• APB ContentLanguageUrl remaps unrouted internal:/alias links to the active-language alias when a published translation exists; otherwise it falls back to the English source (not to another language, and not to /es/node/{id}).
• Listing Views must filter langcode to the current content language or boxed cards keep English titles on prefixed URLs.
• moderation_state is per translation. Archiving Spanish leaves English published.

What does not work

• Overlay JSON Dynamic Page Cache does not vary by language. After a Spanish hit, the unprefixed English JSON URL can serve Spanish copy (and the reverse). Cause: controllers omit languages:language_content. Options: add that cache context, add url.path, or set max-age 0. Ship in the component repos.
• Structure cannot differ per language. A parent added on English appears on Spanish until translated. Options: keep the symmetric contract; add a per-item language visibility field (least invasive product change); or asymmetric Paragraphs (forks trees, breaks JS that assumes one #apb-<component>-{id} per parent). Do not make the host field translatable as a silent default.
• CKEditor bodies are translatable, but APB does not rewrite <a href> inside HTML. Translate those hrefs in the body, or use APB link / feature-box fields.
• Webform labels follow interface language, not content language (see Webform guide).

Live lab: demo.apb.aero.net/international.