Link two distinct pages as locale variants

Developing with Prismic
1

Hi everybody!

I have a website with 2 languages (EN & FR) and some pages are created independently, how can I link two different pages as locale variants, instead of two distinct / independant pages? eg I have a page in french and another page in english, but I want to link them as if they were localized versions of the same page, in order to have my “alternate_languages” filled (I use it to display the meta alternates). Is there any way to do that in Prismic or through the API? Or I need to create the locale variants and copy content from the other page, then delete it?

Another option would be to populate alternate_languages with a custom value, sort of

if page.uid == “mypageinfrench" then page.alternate_languages = prismic.api.getByUID('page', "mypageinenglish", { lang : 'en' })

What do you think?

Thanks for the help!

2

Hey @marketing27,

Thanks for raising this :slight_smile: I believe you also sent us a ticket on the Support portal. You'll get a reply there! Let us know if you need further help.

3

Yes thank you for your answer, problem solved we are populating the alternate_languages field with custom values in our code directly!

I copy here the full answer for the community:

—

In Prismic, documents can only be linked as language variants at creation time. Existing, independent pages can’t later be “merged” into a localized group, either in the UI or via the API.

From the docs:

Alternate language pages are linked to their master document when creating them (e.g. via the masterLanguageDocument option in the Migration API).
“It’s not possible to establish this link” after the fact.

Official Prismic way (to have alternate_languages filled)

You’d need to:

  1. Pick one document as the “master” language (say EN or FR).

  2. Create a new document in the other locale as the localized variant of that master:

    • In the Page Builder: use the locale switcher to create the localized version from the existing page.
    • Or via the API/Migration API: create a new document and link it using masterLanguageDocument.

  3. Copy over the content from the existing independent page to this new localized document.

  4. Unpublish/delete the old independent page.
    After that, alternate_languages will be populated automatically and you can use it for meta alternates.

Custom code workaround

If your only goal is correct [link rel="alternate" hreflang="..."] tags, you can handle this purely in code:

Keep the pages independent in Prismic.
On the frontend, detect special cases and manually map them, e.g.:

const alternates = [];

if (page.uid === "xxx" && page.lang === "fr-fr") {
const enDoc = await client.getByUID("page", "yyy", { lang: "en-gb" });
alternates.push(enDoc);
}

Then use this alternates array to render your meta alternate tags.

Notes:

  • You cannot persist or modify alternate_languages in Prismic by assigning to it in code (like page.alternate_languages = ...); that only affects your in-memory object.
  • This workaround is fine for rendering SEO tags but won’t show the link between pages inside Prismic’s UI.
1 Like