Content Manager i18n Preview#

Preview in the Strapi Content Manager lets editors open a live preview of their content in a front-end application. When the content type has i18n enabled, the correct locale must be propagated through the full request chain: from the admin UI query string, through the preview controller's validation layer, into the Document Service's locale filtering pipeline. A gap at any step produces a wrong-locale preview URL or an unhandled error.

Entry points:

Request Chain Overview#

Admin UI (Preview.tsx / PreviewSidePanel.tsx)
  → GET /content-manager/preview/url/:contentType?documentId=&locale=&status=
      → validatePreviewUrl() [validation/preview.ts]
          → previewService.getPreviewUrl(uid, params)
              → user-defined handler(uid, { documentId, locale, status })

Frontend locale source: Preview.tsx reads plugins.i18n.locale from the URL query string via useQueryParams and passes it as the locale query parameter 1. PreviewSidePanel.tsx reads document.locale from the already-loaded document object and passes it directly 2. Both components pre-warm the RTK Query cache so the /preview route loads the URL instantly.

Route: The endpoint is an admin-only GET at /preview/url/:contentType, authenticated via the admin::isAuthenticatedAdmin policy. No i18n middleware (validateLocaleCreation) is registered on this route; locale existence is not validated against the database at this layer 3.

Validation Layer: validatePreviewUrl#

validatePreviewUrl in validation/preview.ts is responsible for sanitising request params before they reach the user-defined handler. Key behaviours:

• Schema: documentId (optional), locale (nullable, optional), status (optional) — validated with Zod 4. locale is accepted as null, meaning an explicit locale=null passes through.
• Content type guard: Throws ValidationError('Invalid content type') if the uid resolves to a non-content-type model 5.
• Collection type guard: Throws ValidationError('documentId is required for Collection Types') when documentId is absent for a collection type 6.
• Single-type documentId resolution: For single types, documentId is optional in the request but required by the handler interface. The validation layer resolves it by calling strapi.documents(uid).findFirst() — with no locale filter — and sets newParams.documentId from the result 7. If no document exists, it throws NotFoundError('Document not found').
• Default status: If status is absent, it defaults to 'draft' for Draft & Publish-enabled types and 'published' otherwise 8.

i18n gap: findFirst() called here is unfiltered by locale. For single types, it returns the first locale entry found in the database, which may not match the locale param the caller passed. The locale value flows to the handler unchanged but the documentId was resolved without locale scope. This is benign when a single-type document's documentId is shared across all locales (the handler should use locale to select the right translation), but could mislead if the handler relies on documentId alone.

Document Service Locale Filtering#

Within the Document Service's repository.ts, every read operation pipes through a fixed locale transform sequence 9:

1. i18n.defaultLocale(contentType) — if the content type is localized and no locale was provided, fetches the system default locale from the i18n plugin and inserts it into params.locale 10.
2. i18n.localeToLookup(contentType) / i18n.multiLocaleToLookup(contentType) — translates params.locale into params.lookup.locale, which is later applied as a WHERE filter at the database level 11.

findFirst (used by single-type documentId resolution in validation) applies localeToLookup, meaning a locale already present in params will be scoped 12. However, since validatePreviewUrl calls findFirst() with no locale argument, the defaultLocale transform will always fall back to the system default locale, not the requested one.

Locale format validation (checkLocale in repository.ts) applies BCP 47 format checks only when config.api.documents.strictParams is true (the default is off) 13. No check against the configured-locales table is performed here. That existence check lives exclusively in the i18n plugin's validateLocaleCreation middleware, which is registered only on standard Content Manager collection/single-type routes — not on the preview route 14.

Known Issues and Edge Cases#

Locale-restricted roles + no locale in URL (issue #27247): When a user's role restricts locale access and they land on a localized single/collection type with no locale in the query string, the default-locale resolution path triggers a 403 Forbidden with a generic error screen instead of the locale-permission messaging shown when switching locale explicitly 15. This is a gap between the explicit-locale-switch path (which has graceful handling) and the implicit default-locale path.

Preview route skips i18n locale-existence middleware: Unlike standard Content Manager routes, the preview URL endpoint (GET /preview/url/:contentType) does not have validateLocaleCreation middleware applied. An invalid (but syntactically plausible) locale string will reach the user-defined handler without a database existence check 14. This is consistent with the Content API behavior but inconsistent with the standard CM edit-view behavior.

Single-type documentId resolved without locale: The findFirst() call in validatePreviewUrl uses the system default locale (via defaultLocale transform), not the locale the caller requested. For i18n single types, the documentId is locale-independent (all locales of a single-type document share the same documentId), so this is functionally correct in Strapi's data model — but the handler must use the passed locale param to select the right translation, not make assumptions based on documentId alone 7 12.

Key Files Reference#