Document envelope

Identity, route, locale, and fallback facts on localized document results.

Document-returning queries—one, many, paginate, resolveOne().doc, backlinks, populated references, and useContentPage—return a localized document envelope. Navigation trees and surround() return smaller navigation-item shapes instead.

type LocalizedContentDocument<T = ParsedContentMeta> = Omit<T, 'path' | 'resolved'> & {
  locale: string
  route: ContentDocumentRoute
  resolution: ContentDocumentResolution
  stem?: string
  extension?: string
  resolvedRefs?: Record<string, string>
}

interface ContentDocumentRoute {
  requestedPath?: string
  resolvedPath: string
  alternates: ContentAlternate[]
}

interface ContentDocumentResolution {
  requested: { locale?: string }
  resolved: { locale: string }
  usedFallback: boolean
}

type ContentAlternate =
  | { locale: string, path: string, source: 'variant' }
  | {
      locale: string
      path: string
      source: 'fallback'
      resolvedLocale: string
    }

Identity

Field	Meaning
`id`	Fully qualified public document identifier
`collection`	Canonical collection name
`canonicalKey`	Opaque locale-independent join key; never parse or render it as a URL
`file`	Optional source-file provenance; absent for providers without backing files
`locale`	Convenience copy of `resolution.resolved.locale`

file.path, when present, is source provenance rather than a public route.

Route

Field	Meaning
`route.requestedPath`	Route or path selector supplied to this resolution, when applicable
`route.resolvedPath`	Canonical public URL for the returned document
`route.alternates`	Proven concrete variants and the fallback route used by this resolution

Use route.resolvedPath for <NuxtLink> and navigateTo():

vue

<NuxtLink :to="article.route.resolvedPath">
  {{ article.title }}
</NuxtLink>

Resolution

resolution.requested.locale is the requested locale, when one was supplied. resolution.resolved.locale is the variant that produced the document. resolution.usedFallback is true when those locales differ because fallback succeeded.

Alternates

A source: 'variant' entry is a concrete translation returned by the provider. A source: 'fallback' entry records the requested route that this query actually resolved with content from resolvedLocale.

Ginko does not invent fallback URLs for other missing locales from one document. Whole-collection surfaces such as sitemaps use the canonical route index, where all route facts are available.

vue

<NuxtLink
  v-for="alternate in page.route.alternates"
  :key="`${alternate.locale}:${alternate.path}`"
  :to="alternate.path"
>
  {{ alternate.locale }}
</NuxtLink>

Applications can label or suppress source: 'fallback' entries when a language switcher should expose only concrete translations.

Projection

select removes unselected authored and parsed fields, but Ginko preserves identity plus locale, route, and resolution. Populated fields are also retained. The result remains safe to identify and link after a narrow projection.

The current envelope has no top-level path, variants, localePaths, or resolved. Use the Ginko version migration when replacing those older shapes rather than adding compatibility aliases.