Exposing translation metadata to plugins and themes

[Rimander]

TL;DR

Plugins and themes need translation metadata for language switchers, SEO, sitemaps, analytics, and cache invalidation. I propose a hybrid API: cheap scalars (translationGroup, fallbackLocale) on PublicPageContext; queryable lists behind family helpers (content.getTranslations, taxonomies.getTranslations, menus.getTranslations).

The two options considered

• (a) Everything on PublicPageContext. Eager list of translations on every render.
• (b) Helpers only. Minimal context, every read goes through a function call.

Pure (a) costs a query per render even when nothing reads it, bloats the public type surface, and is unreachable from non-render callers. Pure (b) forces a function call to read a string we already have, encouraging duplicate fetches. Hybrid wins on every column:

How other CMSs do it

• WPML: wpml_object_id, wpml_element_translations.
• Polylang: pll_get_post_translations($id), pll_current_language().
• Yoast / Rank Math: consume WPML/Polylang APIs to emit hreflang — they don't reimplement multilingual.
• Drupal: \Drupal::languageManager(), $entity->getTranslationLanguages().

Shared pattern: translation metadata is a first-class system concept, available to any caller, not baked into a render context.

The hybrid: precise definitions

Scalars on PublicPageContext

interface PublicPageContext {
  // ... existing fields ...

  /**
   * The ULID shared by every translation of the current content entry.
   * `null` when the page is not content-backed or i18n is disabled.
   * After migration 019, every content row has one — solo entries are their own group.
   */
  translationGroup: string | null;

  /**
   * The locale actually served, when it differs from the locale the request asked for.
   * `null` when the request locale matched exactly. Page-level only — not set for
   * field-level fallback. Sourced from `EntryResult.fallbackLocale`.
   */
  fallbackLocale: string | null;
}

Both are scalars already computed during entry resolution. Adding them costs zero queries.

Family helpers (signatures)

// packages/core/src/query.ts (or per-module)
namespace content {
  /**
   * @param type    Collection slug as defined in `_emdash_collections.slug`
   *                (e.g. "posts", "pages", "products"). Maps to `ec_{type}`.
   * @param id      Entry ULID — primary key of the row in `ec_{type}`.
   * @param options publishedOnly defaults to `true` on the public path.
   * @returns       Sibling rows in the same `translation_group`, excluding the
   *                input id, filtered by `deleted_at IS NULL`.
   */
  function getTranslations(
    type: string,
    id: string,
    options?: { publishedOnly?: boolean },
  ): Promise<ContentTranslationSummary[]>;
}

interface ContentTranslationSummary {
  id: string;            // entry ULID
  locale: string;        // BCP-47 locale code, e.g. "en", "es-MX"
  slug: string;
  status: "draft" | "published" | "archived";
  publishedAt: string | null;  // ISO 8601
  url: string | null;    // resolved public URL when integration provides a builder
}

namespace taxonomies {
  /**
   * @param taxonomy Taxonomy slug as defined in `_emdash_taxonomy_defs.slug`
   *                 (e.g. "categories", "tags").
   * @param id       Term ULID — primary key in `taxonomies`.
   */
  function getTranslations(
    taxonomy: string,
    id: string,
  ): Promise<TaxonomyTranslationSummary[]>;
}

interface TaxonomyTranslationSummary {
  id: string;            // term ULID
  locale: string;
  slug: string;
  name: string;
}

namespace menus {
  /** @param id Menu ULID — primary key in `_emdash_menus`. */
  function getTranslations(id: string): Promise<MenuTranslationSummary[]>;
}

interface MenuTranslationSummary {
  id: string;            // menu ULID
  locale: string;
  name: string;
}

All three resolve via one private function:

// internal — not exported
async function resolveTranslationGroup(
  table: string,         // validated against allowlist; never user-supplied
  id: string,
  filters: { publishedOnly?: boolean },
): Promise<{ translationGroup: string; rows: unknown[] }>;

The rule: scalars we already have go on the context; anything that costs a query goes through a typed family helper. All helpers use requestCached so multiple consumers in one render share a single fetch.

Why family helpers (not polymorphic, not low-level)

Three shapes considered:

• (1) One polymorphic helper getTranslations(kind, id) with kind: "content:posts" | "taxonomy:categories" | …. Forces a discriminated union return type, and kind strings leak storage layer naming into the public API.
• (2) Family helpers as defined above.
• (3) Public low-level resolver + thin wrappers. Same surface as (2) plus an exposed resolveTranslationGroup(table, id). The extra surface buys nothing.

I choose (2) because:

1. Matches existing module layout (content/, taxonomies/, menus/ each own their helpers).
2. Each return type is precise — no LCD shape, no narrowing on every call.
3. No leaky discriminators: content.getTranslations("posts", id) reads as intent, not as a table name.
4. Shared logic stays DRY internally via the private resolver.
5. Non-render callers (cron, sitemap, webhooks) use the same API — no PublicPageContext required.

Open questions

1. Existing getTranslations(type, id) in packages/core/src/query.ts is content-only, returns drafts, and is used by the admin switcher. Pick one:
   (i) replace it with content.getTranslations and add { includeDrafts: true } for the admin path;
   (ii) keep both, public-safe vs. admin;
   (iii) single helper with { publishedOnly: boolean } defaulting to true. Preference: (iii), pending an audit of current callers.
2. Sandboxed plugins get the scalars by default (flat strings, no PII). The three family helpers gate on each family's existing read capability (content:read, taxonomies:read, menus:read). No new capability needed.