Assistance Needed with Implementing Localization in Next.js with Payload CMS 3.0

[brianFrizzera]

Hi, Friends!

I'm developing a web application using Payload CMS 3.0, incorporating the website template for a portion of the app. My goal is to implement localization by structuring my URLs to include locale codes, such as:

• https://domain.com/pt/posts/teste
• https://domain.com/en/home

While attempting to set up dynamic routing with [locale]/[slug], I've encountered issues where only the default locale works, and only for the home page (e.g., https://domain.com/pt or https://domain.com/pt/home). Although implementing localization solely in Next.js is straightforward, I'm unsure about the best practices for integrating localization within Payload CMS and have tried modifying the existing code accordingly.

Problem

I'm encountering routing conflicts when setting up [locale]/[slug] paths. Specifically:

• Default Locale Functionality: Only the default locale functions correctly, and only for the home page.
• Non-Default Locales: Routes with non-default locales do not render as expected and is a 404.

[HarleySalas]

If you'd like to share an example repo for how you're currently doing it, I'd be happy to take a look. This thing is something I've done for quite a few projects and next-intl is usually my preference.

I do run things a bit differently. In any case, I also have a public repo with an older version of Payload, when it was in beta. I haven't gotten the chance to update it yet, as it's just a hobby project. But, it may still be enough to get you going.
https://github.com/conqdb/conqdb/tree/main/apps/web I forgot, that one doesn't have completely dynamic pages, my bad!

[brianFrizzera]

Thank you very much! You helped me a lot.

I had to make some changes, almost all of them related to updating some parts of legacy code. The rest was just integrating it with Payload.

Thanks again, especially for offering to help me with the code in my repo.

Best regards!

[ZorbaBuda]

Hey! Same here. I started learning Payload 3.0.
For practice, I want to recreate in Payload 3 a website localized in two languages, that project uses next-intl .
As of now, I am practicing with just one language, but soon or later will need to be able to use two languages, and I am not
seeing too much info about how manage this.

[brianFrizzera]

@ZorbaBuda, This might also be useful for you:

#9435 (reply in thread)

[bhofstaetter]

I'm also trying to integrate next-intl into my payload project, but haven't managed to combine the next-intl middleware with mine yet. has anyone had a similar case and could help? I'm pretty new to nextjs and payload, probably there is a better approach to do this?

here's my custom middleware.ts

export const middleware = async (request: NextRequest) => {
    // ---------------------------------------------------------------------------------
    // header anreichern
    // ---------------------------------------------------------------------------------

    const requestHeaders = request.headers;
    const modifiedHeaders = new Headers(requestHeaders);

    const host = requestHeaders.get('host') ?? '';
    const protocol = requestHeaders.get('x-forwarded-proto') ?? 'https';

    const hostname = host.split(':')[0];
    const origin = `${protocol}://${host}`;

    const {pathname, searchParams} = request.nextUrl;
    const searchParamsString = searchParams.toString() ? `?${searchParams.toString()}` : '';

    const customHeaders = [
        {name: X_HEADER_DOMAIN, value: hostname},
        {name: X_HEADER_PATHNAME, value: pathname},
        {name: X_HEADER_BASE_URL, value: origin},
        {name: X_HEADER_SEARCH_PARAMS, value: searchParamsString},

        {name: X_HEADER_LOCALE, value: searchParams.get('locale')},
        {name: X_HEADER_DRAFT_MODE, value: searchParams.get('draftMode')},
        {name: X_HEADER_LIVE_PREVIEW, value: searchParams.get('livePreview')},
        {name: X_HEADER_REDIRECT_BACK, value: searchParams.get('redirectBack')},
    ];

    customHeaders.forEach((header) => {
        if (header.value) {
            modifiedHeaders.set(header.name, header.value);
        }
    });

    const newResponse = NextResponse.next({
        request: {
            headers: modifiedHeaders,
        },
    });

    // ---------------------------------------------------------------------------------
    // folgende routen sollen nicht weiter bearbeitet werden
    // ---------------------------------------------------------------------------------

    if (
        pathname.startsWith(ROUTE_API) ||
        pathname.startsWith(ROUTE_STATIC) ||
        pathname.startsWith(ROUTE_ADMIN) ||
        pathname.startsWith(ROUTE_NEXT) ||
        /\.(.*)$/.test(pathname) // dateien im "public" ordner
    ) {
        return newResponse;
    }

    // ---------------------------------------------------------------------------------
    // sicherstellen das nur die tenant hauptdomain verwendet wird
    // ---------------------------------------------------------------------------------

    try {
        const result = await typedFetch<GetPrimaryDomainResponse>(`${origin}${ROUTE_API}/tenants/primarydomain`, {
            headers: {
                [X_HEADER_DOMAIN]: hostname,
            },
        });

        const primaryDomain = result.json.primaryDomain;

        if (primaryDomain && primaryDomain !== hostname) {
            const primaryDomainUrl = new URL(origin);

            primaryDomainUrl.hostname = primaryDomain;

            return NextResponse.redirect(primaryDomainUrl.toString(), {
                status: 301,
            });
        }
    } catch (err) {
        console.warn('problem while primary domain redirect', err);
    }

    // ---------------------------------------------------------------------------------
    // dauerhaft geschützte routen absichern
    // ---------------------------------------------------------------------------------

    const loggedInUser = await getLoggedInUser();

    const protectedRoutes = ['/du-kommst-hier-nicht-rein'];

    if (!loggedInUser && protectedRoutes.includes(pathname)) {
        try {
            const redirectUrl = new URL(origin);
            const redirectSearchParams = new URLSearchParams({
                redirectBack: encodeURI(pathname + searchParamsString),
            });

            redirectUrl.pathname = ROUTE_LOGIN;
            redirectUrl.search = redirectSearchParams.toString();

            return NextResponse.redirect(redirectUrl.toString());
        } catch (err) {
            console.warn('problem while redirecting protected route to login', err);
        }
    }

    return newResponse;
};

[bhofstaetter]

my livepreview url function looks like this

import {COLLECTIONS_ROUTE_MAPPING, ROUTE_LIVE_PREVIEW_UNAVAILABLE} from '@/shared/constants';
import {LivePreviewConfig} from 'payload';
import {getPathname} from '@/shared/i18n/routing';

interface LivePreview extends LivePreviewConfig {
    collections?: string[];
}

export const livePreview: LivePreview = {
    url: ({data, collectionConfig, locale}) => {
        const collectionSlug = collectionConfig?.slug;
        const collectionRoute = COLLECTIONS_ROUTE_MAPPING[collectionSlug!];

        const pathConfig = {
            locale: locale.code,
            href: {
                pathname: ROUTE_LIVE_PREVIEW_UNAVAILABLE,
                query: {livePreview: 1},
            },
        };

        if (!collectionRoute || !data.slug) {
            return getPathname(pathConfig);
        }

        pathConfig.href.pathname = `${collectionRoute}/${data.slug}`.replace('//', '/');

        return getPathname(pathConfig);
    },
    collections: ['pages', 'news'],
};

if you've setup next-intl correct, it should do the job - at least for me :D

could you show your code?

[MarkWestside]

I basically have the standard preview code from the website template. Your configuration is probably from the payload config, isn’t it?

// collections/Pages/index.ts

  admin: {
    defaultColumns: ['title', 'slug', 'updatedAt'],
    livePreview: {
      url: ({ data, req }) => {
        const path = generatePreviewPath({
          slug: typeof data?.slug === 'string' ? data.slug : '',
          collection: 'pages',
          req,
        })

        return path
      },
    },
    preview: (data, { req }) =>
      generatePreviewPath({
        slug: typeof data?.slug === 'string' ? data.slug : '',
        collection: 'pages',
        req,
      }),
    useAsTitle: 'title',
  },

// payload.config.ts

  admin: {
    components: {
      // The `BeforeLogin` component renders a message that you see while logging into your admin panel.
      // Feel free to delete this at any time. Simply remove the line below and the import `BeforeLogin` statement on line 15.
      beforeLogin: ['@/components/BeforeLogin'],
      // The `BeforeDashboard` component renders the 'welcome' block that you see after logging into your admin panel.
      // Feel free to delete this at any time. Simply remove the line below and the import `BeforeDashboard` statement on line 15.
      beforeDashboard: ['@/components/BeforeDashboard'],
    },
    importMap: {
      baseDir: path.resolve(dirname),
    },
    user: Users.slug,
    livePreview: {
      breakpoints: [
        {
          label: 'Mobile',
          name: 'mobile',
          width: 375,
          height: 667,
        },
        {
          label: 'Tablet',
          name: 'tablet',
          width: 768,
          height: 1024,
        },
        {
          label: 'Desktop',
          name: 'desktop',
          width: 1440,
          height: 900,
        },
      ],
    },
  },

No idea what your constants are, but now I know that the locale is available within the url function. Thank you for that. I still have to get my head around how Payload is set up.

How does your pathConfig work?

PS: Your Payload enchantments look very cool! I’ll definitely try them out!

[bhofstaetter]

yes, what i have posted is my live preview configuration inside the payload config. to keep everything organized, i have moved it to a separate file.

COLLECTIONS_ROUTE_MAPPING is just an object that contains the frontend routes for each collection

ROUTE_LIVE_PREVIEW_UNAVAILABLE is a placeholder for a route with an error message if the live preview is not available.

pathConfig are the parameters for the getPathname function of next-intl to assemble the correct path which respects the current locale.

with small adjustments, you can also use the configuration within a collection. however, i wanted to have it centrally once and not maintain it in every collection.

thanks, but which enhancements do you mean?

[MarkWestside]

I see, I think my problem is that the page itself uses NEXT_LOCALE for its queries instead of the preview locale in queryPageBySlug at the very end:

import type { Metadata } from 'next'

import { PayloadRedirects } from '@/components/PayloadRedirects'
import configPromise from '@payload-config'
import { getPayload, TypedLocale } from 'payload'
import { draftMode } from 'next/headers'
import React, { cache } from 'react'
import { homeStatic } from '@/endpoints/seed/home-static'

import type { Page as PageType } from '@/payload-types'

import { RenderBlocks } from '@/blocks/RenderBlocks'
import { RenderHero } from '@/heros/RenderHero'
import { generateMeta } from '@/utilities/generateMeta'
import PageClient from './page.client'
import { LivePreviewListener } from '@/components/LivePreviewListener'

export async function generateStaticParams() {
  const payload = await getPayload({ config: configPromise })
  const locales: TypedLocale[] = ['de', 'en']

  const pages = await payload.find({
    collection: 'pages',
    draft: false,
    limit: 1000,
    overrideAccess: false,
    pagination: false,
    select: {
      slug: true,
    },
  })

  const params = pages.docs
    ?.filter((doc) => {
      return doc.slug !== 'home'
    })
    .map(({ slug }) => {
      return locales.map((locale) => ({ slug, locale }))
    })

  return params
}

type Args = {
  params: Promise<{
    slug?: string
    locale: TypedLocale
  }>
}

export default async function Page({ params: paramsPromise }: Args) {
  const { isEnabled: draft } = await draftMode()
  const { slug = 'home', locale } = await paramsPromise
  const url = '/' + slug

  let page: PageType | null

  page = await queryPageBySlug({
    slug,
    locale,
  })

  // Remove this code once your website is seeded
  if (!page && slug === 'home') {
    page = homeStatic
  }

  if (!page) {
    return <PayloadRedirects url={url} />
  }

  const { hero, layout } = page

  return (
    <article className="pt-16 pb-24">
      <PageClient />
      {/* Allows redirects for valid pages too */}
      <PayloadRedirects disableNotFound url={url} />

      {draft && <LivePreviewListener />}

      <RenderHero {...hero} />
      <RenderBlocks blocks={layout} />
    </article>
  )
}

export async function generateMetadata({ params: paramsPromise }): Promise<Metadata> {
  const { slug = 'home', locale } = await paramsPromise
  const page = await queryPageBySlug({
    slug,
    locale,
  })

  return generateMeta({ doc: page })
}

const queryPageBySlug = cache(async ({ locale, slug }: { locale: TypedLocale; slug: string }) => {
  const { isEnabled: draft } = await draftMode()

  const payload = await getPayload({ config: configPromise })

  const result = await payload.find({
    collection: 'pages',
    draft,
    limit: 1,
    pagination: false,
    overrideAccess: draft,
    locale,
    where: {
      slug: {
        equals: slug,
      },
    },
  })

  return result.docs?.[0] || null
})

My way of including the locale ignores the preview config. How did you include the locale in the page query functions?

I was talking about your payload-enchants repo.

[bhofstaetter]

That's not my repo, i found it somewhere in the discussions, liked the ideas and forked it. Unfortunately, I haven't had the chance to try anything out yet.

Since i'm still working on backend topics, i haven't implemented the data query yet. Here is a very rudimentary, but "working" example of how it works. tested with live preview.

const Page = async (props: any) => {
    const {locale, slug} = await props.params;

    const page = await configuredPayload
        .find({
            collection: 'pages',
            locale,
            where: {
                slug: {
                    equals: slug,
                },
            },
        })
        .then((results) => results.docs)
        .then((docs) => docs[0]);

    return <h1>{page.title}</h1>;
};

export default Page;

what do you mean with "My way of including the locale ignores the preview config."?