Localized website template #9997

vatro · 2024-12-16T17:19:59Z

vatro
Dec 16, 2024

An additional, localized website template (based on the single language template) would be awesome:

Two languages (en + xx)
Localized folder structure
Middleware
Localized Redirect Plugin
Language switcher
Dictionary
Root layout modifications
Working preview / live preview
Some API examples
README.md / Localization Docs:
Best practices concerning collections & fields localization, e.g. what should be localized in different scenarios incl. caveats.
- Preserving content structure across languages (where to / not add the localized property)
- Different content structure per language (where to / not add the localized property)
- Introduce possible (common / best) localization strategies
- SEO remark: SEO meta is localized out-of-the-box, not need to modify anything, see Metadata in Docs
- Examples of field migration strategies when changing the localized property, see corresponding remark in docs: https://payloadcms.com/docs/configuration/localization
  
  Before changing the Localization setting on fields with existing data, you may need to consider a field migration strategy.
- Best practice development workflows for maximum flexibility / painless modifications (e.g. editing / replacing components of a website that already has a ton of content added across multiple languages).

The most awesome would be a new CLI command, like e.g. npx create-payload-app -n my-project -t website --localized en,xx generating a basic localized website template with specified languages already set up "properly" (default: preserve content layout across languages) + an optional flag --preserve yes | no (default: yes).

Robust and flexible localization options are crucial for any company / website based in a non-English speaking country doing international business.

I'm currently converting the single language website template to a localized one, these are the things I had to do / touch so far, not mentioned in the Docs (https://payloadcms.com/docs/configuration/localization) - will update it as I go forward:

Localized Frontend

Use dynamic [lang] route: move the contents of src/app/(frontend)/ into src/app/(frontend)/[lang]/

Modify src/app/(frontend)/[lang]/layout.tsx to set lang attribute on <html>:

  import type { Config } from '@/payload-types'

  export default async function RootLayout({
    children,
    params,
  }: {
    children: React.ReactNode
    params: Promise<{ lang: Config['locale'] }>
  }) {
    const { isEnabled } = await draftMode()
    const { lang } = await params
  
    return (
      <html
        className={cn(GeistSans.variable, GeistMono.variable)}
        lang={lang}

        ...

Modify src/app/(frontend)/[lang]/[slug]/page.tsx to use the lang param in:

Page: use lang

type Args = {
   params: Promise<{
     slug?: string
     lang?: Config['locale']
   }>
 }
 
 export default async function Page({ params: paramsPromise }: Args) {
   const { slug = 'home', lang = 'en' } = await paramsPromise
   const url = '/' + slug
 
   let page: PageType | null
 
   page = await queryPageBySlug({
     slug,
     lang,
   })

generateMetadata: use lang

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

   return generateMeta({ doc: page })
 }

queryPageBySlug: use lang and set localeto lang

const queryPageBySlug = cache(async ({ slug, lang }: { slug: string; lang: Config['locale'] }) =>

const result = await payload.find({
collection: 'pages',
locale: lang,
fallbackLocale: false,
...

generateStaticParams: set locale in payload.find to fetch a language / fetch multiple languages.

Localized Slugs

src/fields/slug/index.ts

const slugField: TextField = {
  name: 'slug',
  type: 'text',
+ localized: true,

Localized Live Preview / Preview

src/utilities/generatePreviewPath.ts

- const path = `${collectionPrefixMap[collection]}/${slug}`
+ const path = `${collectionPrefixMap[collection]}/${req.locale}/${slug}`

- const url = `${protocol}//${req.host}/next/preview?${encodedParams.toString()}`
+ const url = `${protocol}//${req.host}/${req.locale}/next/preview?${encodedParams.toString()}`

src/app/(frontend)/[lang]/next/preview/route.ts

+ import type { Config } from '@/payload-types'

+ // Get the language from path
+ const lang = path.split('/').filter((item) => item)[0] as Config['locale']

const docs = await payload.find({
...
+ locale: lang,
...
}

Localized Header / Navigation

src/fields/link.ts

localized label, custom url and reference fields

name: 'label',
type: 'text',
+ localized: true,

name: 'url',
type: 'text',
+ localized: true,

name: 'reference',
type: 'relationship',
+ localized: true,

optionally localize the whole header if you need different nav menu per language:

src/Header/config.ts

fields: [
{
name: 'navItems',
type: 'array',
+ localized: true, // allow different nav items per locale

src/app/(frontend)/[lang]/layout.tsx
```
- <Header />
+ <Header locale={lang} />
```

src/utilities/getGlobals.ts
use locale and export getGlobal because we need uncached header data in src/Header/Component.tsx

- async function getGlobal(slug: Global, depth = 0) {
+ export async function getGlobal(slug: Global, depth = 0, locale: Config['locale'] = 'en') {

  const global = await payload.findGlobal({
    slug,
    depth,
+    locale,
  })

- export const getCachedGlobal = (slug: Global, depth = 0) =>
-  unstable_cache(async () => getGlobal(slug, depth), [slug], {
+ export const getCachedGlobal = (slug: Global, depth = 0, locale: Config['locale'] = 'en') =>
+  unstable_cache(async () => getGlobal(slug, depth, locale), [slug], {

src/Header/Component.tsx
use locale and uncached header data in order to get correct data on locale change.

- import { getCachedGlobal } from '@/utilities/getGlobals'
+ import { getGlobal } from '@/utilities/getGlobals'
+ import type { Config } from 'src/payload-types'

- export async function Header() {
-   const headerData: Header = await getCachedGlobal('header', 1)()
+ export async function Header({ locale }: { locale: Config['locale'] }) {
+  const headerData: Header = await getGlobal('header', 1, locale)

👆 not sure about using getGlobal/ not using getCachedGlobal, but it works.

Drill down `locale` to `CMSLink` Component

For localized relational (reference) link-urls, e.g. <host>//[locale]/[slug] instead of <host>//[slug].

src/Header/Component.tsx

- return <HeaderClient data={headerData} />
+ return <HeaderClient data={headerData} locale={locale} />

src/Header/Component.client.tsx

+ import type { Config } from 'src/payload-types'
interface HeaderClientProps {
  data: Header
+ locale: Config['locale']
}

- export const HeaderClient: React.FC<HeaderClientProps> = ({ data }) => {
+ export const HeaderClient: React.FC<HeaderClientProps> = ({ data, locale }) => {

- <HeaderNav data={data} />
+ <HeaderNav data={data} locale={locale}/>

src/Header/Nav/index.tsx

+ import type { Config } from 'src/payload-types'

- export const HeaderNav: React.FC<{ data: HeaderType }> = ({ data }) => {
+ export const HeaderNav: React.FC<{ data: HeaderType, locale: Config['locale'] }> = ({ data, locale }) => {

- return <CMSLink key={i} {...link} appearance="link" />
+ return <CMSLink key={i} {...link} locale={locale} appearance="link" />

src/components/Link/index.tsx (CMSLink Component)

+ import type { Config } from 'src/payload-types'

type CMSLinkType = {
+ locale: Config['locale']
}

export const CMSLink: React.FC<CMSLinkType> = (props) => {
+ locale,
} = props

- ? `${reference?.relationTo !== 'pages' ? `/${reference?.relationTo}` : ''}/${
+ ? `${reference?.relationTo !== 'pages' ? `/${reference?.relationTo}` : ''}/${locale}/${

⚠️ Localized Redirects via `@payloadcms/plugin-redirects`

Wasn't successful with fully localizing it.
Was able to localize the to fields (reference and custom URL), but not the from field: e.g. /home slug doesn't take current locale into account, also /xx/home slug doesn't work and I couldn't find the way how to inject the current locale into the from: value, I guess this could be done with a hook. That's why I'm currently using middleware for redirects instead of the plugin.

ali-issa · 2024-12-18T06:21:21Z

ali-issa
Dec 18, 2024

This is definitely much needed. The localization docs are really confusing as they stand. There's no clear, step-by-step guide to walk users through setting up a fully localized website. The documentation mentions various necessary steps, but it doesn't explain how to actually implement them. It would be a huge improvement if, when you enable localization in the config of a fresh website with the default demo data, a script would automatically update the field configurations of the existing structure. Even better, that script should also add a basic language select component so users can immediately start testing the localization. That would make the whole process so much smoother and more intuitive.

0 replies

tarikkavaz · 2024-12-18T23:57:06Z

tarikkavaz
Dec 18, 2024

I would love this! I’m even willing to settle for better documentation or a tutorial, but this feature would be a dream.

2 replies

vatro Dec 19, 2024
Author

I'm currently converting the single language website template to a localized one, these are the things I had to do / touch so far, not mentioned in the Docs (https://payloadcms.com/docs/configuration/localization):

Localized Frontend

Use dynamic [lang] route: move the contents of src/app/(frontend)/ into src/app/(frontend)/[lang]/

Modify src/app/(frontend)/[lang]/layout.tsx to set lang attribute on <html>:

  import type { Config } from '@/payload-types'

  export default async function RootLayout({
    children,
    params,
  }: {
    children: React.ReactNode
    params: Promise<{ lang: Config['locale'] }>
  }) {
    const { isEnabled } = await draftMode()
    const { lang } = await params
  
    return (
      <html
        className={cn(GeistSans.variable, GeistMono.variable)}
        lang={lang}

        ...

Modify src/app/(frontend)/[lang]/[slug]/page.tsx to use the lang param in:

Page: use lang

type Args = {
   params: Promise<{
     slug?: string
     lang?: Config['locale']
   }>
 }
 
 export default async function Page({ params: paramsPromise }: Args) {
   const { slug = 'home', lang = 'en' } = await paramsPromise
   const url = '/' + slug
 
   let page: PageType | null
 
   page = await queryPageBySlug({
     slug,
     lang,
   })

generateMetadata: use lang

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

   return generateMeta({ doc: page })
 }

queryPageBySlug: use lang and set localeto lang

const queryPageBySlug = cache(async ({ slug, lang }: { slug: string; lang: Config['locale'] }) =>

const result = await payload.find({
collection: 'pages',
locale: lang,
fallbackLocale: false,
...

generateStaticParams: set locale in payload.find to fetch a language / fetch multiple languages.

Localized Live Preview / Preview

Modify src/utilities/generatePreviewPath.ts

- const path = `${collectionPrefixMap[collection]}/${slug}`
+ const path = `${collectionPrefixMap[collection]}/${req.locale}/${slug}`

- const url = `${protocol}//${req.host}/next/preview?${encodedParams.toString()}`
+ const url = `${protocol}//${req.host}/${req.locale}/next/preview?${encodedParams.toString()}`

tarikkavaz Dec 19, 2024

thank you! I will check this page again since you are still working on it. 👍🏼

tarikkavaz · 2024-12-20T14:32:05Z

tarikkavaz
Dec 20, 2024

I added localized: true,

{
  name: 'url',
  localized: true,
  ...
}

to src/fields/link.ts on line 84.
Without it, I had only one language's slug; with it, I get both slugs.
I hope this is the right approach.

I couldn't find const url = `${protocol}//${req.host}/next/preview?${encodedParams.toString()}`,
but aside from that, everything else worked with your suggested changes.

I was not able to print the current language's navigation bar in the header. I'm still trying to figure it out.

1 reply

vatro Dec 23, 2024
Author

Hi, see progress updates inside the initial comment 👉 "Localized Header / Navigation" section.

tarikkavaz · 2024-12-29T00:14:51Z

tarikkavaz
Dec 29, 2024

@vatro thank you for your assistance. I successfully translated the website template. It took some time as I needed to modify numerous payload components, but the result turned out well. I'll share the repository once I've finished adding some final touches.

1 reply

notflip Sep 2, 2025

Hi, can you share the repo please?

petrhromadka · 2025-01-03T09:11:50Z

petrhromadka
Jan 3, 2025

Issue: Routes not working correctly for localized URLs (/en/pricing, /en/contact)

When using the official template npx create-payload-app --example localization, I'm experiencing issues with routing for localized URLs. Specifically, the following routes are not working properly:

/en/pricing
/en/contact

Steps to reproduce:

Created new project using npx create-payload-app --example localization
Started the application
Tried accessing /en/pricing and /en/contact URLs

Expected behavior:

Pages should be accessible and display properly with localized content

Current behavior:

Pages are not accessible/routing is not working as expected

Could you please advise on how to properly set up routing for localized URLs in this template? Or share an example of a working implementation?

1 reply

vatro Jan 3, 2025
Author

You should report this issue here: https://github.com/payloadcms/payload/issues.

I didn't even try npx create-payload-app --example localization due to (see README):

This example is built based on an old version of the website template.

There is no guarantee that it will be kept up to date with the website template or the latest Payload enhancements.

Imo there should be an official localized / multilingual website template that's always up-to-date with the newest version of payload / the "standard" website template. That's what this proposal / discussion is about.

tarikkavaz · 2025-01-11T10:11:33Z

tarikkavaz
Jan 11, 2025

Although the template is 'old,' the payload part is the best we have as a boilerplate, minus the issue @petrhromadka mentioned. I believe there is already an issue opened: #9437

0 replies

francoishernandez · 2025-05-21T14:59:56Z

francoishernandez
May 21, 2025

Hi there,

I recently started playing around with payload.
Trying out the localization feature, I found the documentation a bit lacking, and thought it'd be a good exercise, and probably beneficial for the community, to try and adapt the latest website template to match the current localization example.

My PR for reference: #12476

You can also see in the initial PR comment a link to some diffs trying to make things a bit more readable.

Imo there should be an official localized / multilingual website template that's always up-to-date with the newest version of payload / the "standard" website template. That's what this proposal / discussion is about.

I somehow agree on this, but there often is no perfect solution in such context:

embed localization in the main template -- this adds some overhead and complexity, when lots of users probably don't need it;
maintain a separate localized version -- maintenance overheads can quickly lead to misalignment.

1 reply

vatro Jun 3, 2025
Author

when lots of users probably don't need it;
maintenance overheads can quickly lead to misalignment.

After finding out that apparently only ca. 5% of websites are multilingual (despite various benefits), I think that maintaining a separate localized version should be taken care of by those (us) who care (Europe, Japan etc.).

vatro · 2025-06-03T21:24:56Z

vatro
Jun 3, 2025
Author

I wanted to put some more emphasis on this proposal and back it up with some numbers, but then I've learned that only approximately 5% of websites are multilingual 👀 Btw, my multilingual Payload 3 pilot project website is almost finished and I'm very satisfied with Payload 3 as CMS so far. 👍

5 replies

ali-issa Jun 4, 2025

That's awesome to hear! Quick question, are the slugs localized as well? For example, if you're on a post page and switch the language, does it fetch the correct language version of the post and redirect to that specific localized slug?

thierry-rietsch Jun 18, 2025

How did you implemented the localized slugs and – if you do – what approach did you choose to generate the meta alternate href links per supported language?

Btw. where did you get that 5% statistic? Hard to imagine that low number :-)

vitakili Jul 8, 2025

That's awesome to hear! Quick question, are the slugs localized as well? For example, if you're on a post page and switch the language, does it fetch the correct language version of the post and redirect to that specific localized slug?

Did you manage the locale slug switcher?

vatro Jul 10, 2025
Author

@thierry-rietsch

How did you implemented the localized slugs
hat approach did you choose to generate the meta alternate href links per supported language

Look above: #9997 (comment) there are some code examples which should cover that.

Btw. where did you get that 5% statistic? Hard to imagine that low number :-)

I guess here + some double manual research:

vatro Jul 10, 2025
Author

@ali-issa

That's awesome to hear! Quick question, are the slugs localized as well? For example, if you're on a post page and switch the language, does it fetch the correct language version of the post and redirect to that specific localized slug?

Look above: #9997 (comment) there are some code examples which should cover that.

AlexanderProd · 2025-07-10T05:06:15Z

AlexanderProd
Jul 10, 2025

Do I have to make changes to the seeding functionality? Since the seeding of the official 'website' template doesn't work anymore after making these changes.

2 replies

vatro Jul 10, 2025
Author

the official 'website' template uses seeding when creating a new project (website) so you have some initial content, but you don't need that afterwards, I removed the endpoints/seed folder completely at some point.

AlexanderProd Jul 10, 2025

@vatro Yeah I don’t necessarily need it afterwards but it’s a nice starting point and I’m wondering why it wasn’t working anymore after doing the changes for localization. There are no errors either.

notflip · 2025-09-02T23:37:12Z

notflip
Sep 2, 2025

Has anyone used this in production?

0 replies

Localized website template #9997

Uh oh!

Uh oh!

Localized Frontend

Localized Slugs

Localized Live Preview / Preview

Localized Header / Navigation

Drill down locale to CMSLink Component

⚠️ Localized Redirects via @payloadcms/plugin-redirects

Replies: 10 comments · 13 replies

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vatro Dec 19, 2024 Author

Localized Frontend

Localized Live Preview / Preview

Uh oh!

Uh oh!

Uh oh!

vatro Dec 23, 2024 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vatro Jan 3, 2025 Author

Uh oh!

Uh oh!

Uh oh!

vatro Jun 3, 2025 Author

Uh oh!

vatro Jun 3, 2025 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vatro Jul 10, 2025 Author

Uh oh!

vatro Jul 10, 2025 Author

Uh oh!

Uh oh!

Uh oh!

vatro Jul 10, 2025 Author

Uh oh!

Uh oh!

Drill down `locale` to `CMSLink` Component

⚠️ Localized Redirects via `@payloadcms/plugin-redirects`

Replies: 10 comments 13 replies

vatro Dec 19, 2024
Author

vatro Dec 23, 2024
Author

vatro Jan 3, 2025
Author

vatro Jun 3, 2025
Author

vatro
Jun 3, 2025
Author

vatro Jul 10, 2025
Author

vatro Jul 10, 2025
Author

vatro Jul 10, 2025
Author