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

localize label and custom url fields

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

name: 'url',
type: 'text',
+ 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.

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.

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

Replies: 3 comments 2 replies

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

Select a reply

Localized website template #9997

vatro Dec 16, 2024

Localized Frontend

Localized Live Preview / Preview

Localized Header / Navigation

Replies: 3 comments · 2 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 16, 2024

Replies: 3 comments 2 replies

ali-issa
Dec 18, 2024

tarikkavaz
Dec 18, 2024

vatro Dec 19, 2024
Author

tarikkavaz
Dec 20, 2024