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
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

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()}`

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}/${

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.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Localized website template #9997

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Drill down `locale` to `CMSLink` Component

Replies: 4 comments 3 replies

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

Localized website template #9997

vatro Dec 16, 2024

Localized Frontend

Localized Slugs

Localized Live Preview / Preview

Localized Header / Navigation

Drill down locale to CMSLink Component

Replies: 4 comments · 3 replies

ali-issa Dec 18, 2024

tarikkavaz Dec 18, 2024

vatro Dec 19, 2024 Author

Localized Frontend

Localized Live Preview / Preview

tarikkavaz Dec 19, 2024

tarikkavaz Dec 20, 2024

vatro Dec 23, 2024 Author

tarikkavaz Dec 29, 2024

vatro
Dec 16, 2024

Drill down `locale` to `CMSLink` Component

Replies: 4 comments 3 replies

ali-issa
Dec 18, 2024

tarikkavaz
Dec 18, 2024

vatro Dec 19, 2024
Author

tarikkavaz
Dec 20, 2024

vatro Dec 23, 2024
Author

tarikkavaz
Dec 29, 2024