Localization enhancements

[JessChowdhury]

We aim to improve current localization features with the following items:

1. Renovation of the document status bar to include all locale status information. Related thread here by italodr.
2. Adding the ability to unpublish specific locales

Any other localization enhancements requests are welcome, they will be prioritized and incorporated into the roadmap accordingly.

[rilrom]

Being able to unpublish specific locales really needs to be prioritised. It seems like a fundamental feature for localization.

Currently the only way I can see to unpublish a locale is completely deleting the document and re-implementing it without publishing the specific locale, causing all version history to be lost (which in our case is not practical).

If anyone has any other workarounds I'd appreciate if they could share.

Glad to see it's showing up here for discussion.

[maximseshuk]

@rilrom, I support your view, and here's how I see this improvement for Payload's localization to match Strapi's excellent implementation. We need two key features for collections with translations:

1. Independent Timestamps

   • Each language version should have its own timestamps
   • This makes it easy to track when each translation was last modified

2. Separate Status Controls

   • Each language version needs its own status field (_status)
   • Status options would be: draft, published, or edited (for versions)
   • This allows us to manage different versions of each translation
   • Enables proper API response handling (e.g., return 404 for unpublished translations)

For example: if content ID 5 has English published but French in draft:

• GET /api/content/5?locale=en returns the content (200 OK)
• GET /api/content/5?locale=fr returns not found (404)

This solves the common issue where content exists in some languages but not others, ensuring users only see properly published content in their requested language.

These changes would significantly improve Payload's localization workflow and make it more user-friendly for content managers working with multiple languages.

[italodr]

@maximseshuk I completely agree with your points. These ideas would significantly improve language management.

Additionally, it might be worth exploring the option to manage deletions by language. This could provide greater security and stability for content editors.

Currently, as @rilrom mentioned, the only option is to delete the entire file.

One potential solution could be for the delete button to restore the initial version of the file (empty), allowing individual language versions to be restored later (a kind of soft delete). And, if it’s the only language available, the file would be permanently deleted.

[maximseshuk]

@maximseshuk I completely agree with your points. These ideas would significantly improve language management.

Additionally, it might be worth exploring the option to manage deletions by language. This could provide greater security and stability for content editors.

Currently, as @rilrom mentioned, the only option is to delete the entire file.

One potential solution could be for the delete button to restore the initial version of the file (empty), allowing individual language versions to be restored later (a kind of soft delete). And, if it’s the only language available, the file would be permanently deleted.

Deletion can actually be implemented right now using a custom button and custom query, since deleting a row in the collectionName_locales table isn't difficult.

Drafts will generally cover the deletion-related issues, but I agree - having the ability to delete would make things even better!

[Thisisjuke]

Hello 👋

There are also questions around the locale data model to make it easier to retrieve all slugs for all locales for a document in a given collection.

When generating a sitemap, it is generally better to request the document in a single language rather than using locale: '*'. This avoids unnecessary more efficient data retrieval, especially when generating a sitemap or a list of articles in a single language.

Another use case is language switching. When I fetch a document to display it on my page, it’s helpful to have the slug in other available languages so I can directly link to the corresponding language version on a language switch. For example, in a real life front-end application, there is no way editors will redirect /en/discover-my-product to /fr/discover-my-product, it would switch to /fr/découvrir-mon-produit.

To optimize performance, it would be valuable to have these slugs available directly in a single call to fetch documents from a collection, rather than remapping the data within a PayloadCMS custom endpoint.

One workaround we are doing (that will not work without the discussed "admin unpublish feature") is:

export const afterReadHooks: CollectionBeforeReadHook<any>[] = [
  ({ doc }) => {
    doc.tabs.localizedSlugs = doc.tabs.slug
    return doc
  },
]

So, when we request a collections of documents with locale: 'en', we also save all the values of slugs of the admin in a new variable. this way we can have:

{
    slug: 'discover-my-product',
    localizedSlugs: { en:  'discover-my-product', fr: 'découvrir-mon-produit' }
}

Right now, this works, but the content of localizedSlugs is not related in any way to the _status of the document or the locale. It's simply a mapping of the input values from the admin side, so all slugs are sent to the front end. This means unpublished pages can still appear in my sitemap.xml.

[akantic]

Hi, a thing from me.

Support multiple values in the fallbackLocale query parameter.

I need to get content in all available locales that user supports. For example, a user can specify multiple languages they want to see the content in, so I store it as an array and prioritize in that order. Let's say that the user can speak English, German and Spanish, in that order.

const databaseDocs = [
  {
    title: {
      en: "English 1",
      es: "Espanol 1",
    },
  },

  {
    title: {
      es: "Espanol 2",
    },
  },

  {
    title: {
      es: "Espanol 3",
      de: "Deutsch 3",
    },
  },
];

// output
const queriedDocs = [
  {
    title: "English 1",
  },
  {
    title: "Espanol 2",
  },
  {
    title: "Deutsch 3",
  },
];

Query could be locale=[en, de, es] or locale=en&fallbackLocale=[de, es].

Current workaround
When querying I first need to make sure that at least 1 preferred locale exists.

preferredLocales.forEach((locale, i) => {
    query[`where[or][${i}][title.${locale}][exists]`] = true;
});

This is very nasty, because I rely only on the title property to exist. Since the field is required, the document can not be published before it exists.

Along with that, I'm fetching with locale: all and recursing through the entire document replacing the value of each localized field. Essentially the same as you for the fallback locale, but supporting multiple to be specified.

[akantic]

Also aside from the additional fallback functionality directly in the API, here's another nice localization fallback feature from Contentful described at this page.

Basically it enables content editors to specify "fallback trees" which customizes fallback behavior in any way they want.

[lorenzrabs]

Hello! A client duplicated a german post multiple times. For the client it was really confusing why the english content suddenly had 5 identical posts.

Maybe it would be good to give the user a choice which languages to duplicate.

Another thing thats logical for developers, but not for the clients are empty language pendants ().

[aleksei-a-savitski]

It would be nice to be able to add new locales without code changes.

[atlasgong]

It would be incredibly helpful to be able to set fields to be required: true only in the default locale, while remaining optional (required: false) in others. This would enable fields to fall back to the default locale when not provided in other locales.

Example configuration:

localization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
    fallback: true,
}

A possible implementation for a field could look as such:

{
    name: "someField",
    type: "text",
    required: true,  // required only to default locale ('en')
    localized {
        // overrides required status for non-default locales
        // falls back to defaultLocale if not provided
        required: false 
    }
}

Expected Behaviour:

• In the default locale (e.g. en), someField is required.
• In other locales (e.g. fr), someField is optional. If not provided, it falls back to the value of the required en field.
• Editors can save content in non-default locales without being blocked by missing required fields, as these will default to the primary locale's content.

Or, if someone had more than two locales, it may be better to extend the implementation to allow setting which ones should be required:

{
    name: "someField",
    type: "text",
    required: true, 
    localized: {
        required: ["en", "de"], // required only in 'en' and 'de', optional in other locales
    }
}

[mattiaz9]

• Locale unpublishing is a customization that I make all the time, so it'd be nice to have it by default
• Having the _locale field in the document response. If you try to fetch a locale that doesn't exists there is no way to know if the document is the fallback
• adding an option to set the locale in the link field. For instance, if I need to link to a post with a different locale than the current one.

[linobino1]

I think for editors it's easy to forget about localization, because the localization status and locale switch are not very prominent within the UI.
Imagine a collection with many fields where some are localized, some aren't, it's multiple screens long, maybe some tabs, and so on. Here it would be really nice to have a reference on a per field basis, any maybe even the ability to switch the locale on a per field basis.

I am thinking of a status indicator:
My field label - en ✅, it ✅, fr ❌

If the locales would even be clickable so that you can edit the fields value in the specified locale, regardless of the globally selected locale, that would be awesome.

[mik01aj]

I am thinking of a status indicator: My field label - en ✅, it ✅, fr ❌

Yes, and I'd love to have it also in the list view, to easily spot items that need a translation. Here's a quick mockup I made:

Currently I don't even see a way of easily doing it with a custom component - I'd have to change how the data gets retrieved from the db.

[nachomglz]

Could also be good to have a better way of identifying what locales a document is "using", so that we can do custom fields, columns and whatnot

[nachomglz]

Following up with @lorenzrabs 's comment, I created this issue as I found out that when you duplicate a localized document it actually publishes all the rest of available locales and adds a "null - Copy" title to them, even though the other locales have never been touched.

[cbratschi]

Saw this discussion on Discord and wanted to add my previous discussion points:

#4194

I provided some source code and for instance the currently used data models is:

{
  "locales": {
    "de": {
      "status": "published",
      "createdAt": "2025-01-28T22:03:43.128Z",
      "createdBy": "64d118d7ec4a6f13f2ed0d11",
      "updatedAt": "2025-01-28T22:04:50.712Z",
      "updatedBy": "64d118d7ec4a6f13f2ed0d11",
      "publishedAt": "2025-01-28T22:04:50.712Z",
      "publishedBy": "64d118d7ec4a6f13f2ed0d11"
    },
    "en": {
      "status": "draft",
      "createdAt": "2025-01-28T22:04:00.594Z",
      "createdBy": "64d118d7ec4a6f13f2ed0d11",
      "updatedAt": "2025-01-28T22:04:03.983Z",
      "updatedBy": "64d118d7ec4a6f13f2ed0d11"
    },
    "fr": {},
    "it": {}
  }
}

Basically additional metadata gets saved per language which can be used to check which translations exist. Based on such a structure features can be built on top of it.

[nachomglz]

Another thing I'd like to add, I realized that when you enable localization in the Payload app, it adds the "Publish In [Locale]" button to the editing screen.

The problem is that this button also appears in "Non-localized" collections that have versioning enabled, which creates a lot of confusion and insecurity in the editors.

I went ahead and dove a little deeper to see how this works at DB level, and realized that even for "Non-localized" collections—locale tables are created, where there's an entry for each of the documents in the "Non-localized" collection and for each locale, although they don't update at all, meaning the "Publish in [locale]" button doesn't really do anything aside from the normal behaviour of the "Publish version" button. However, I think it's pretty confusing, and also weird that "localized" tables are created for documents that don't have any localized fields whatsoever.