Skip to main content

The localizations field does not exist anymore

In Strapi 5, the localizations field does not exist anymore, and this might restrict the possible use cases.

This page is part of the breaking changes database and provides information about the breaking change and additional instructions to migrate from Strapi v4 to Strapi 5.

🔌 Is this breaking change affecting plugins?Yes
🤖 Is this breaking change automatically handled by a codemod?No

Breaking change description​

In Strapi v4

  • A localizations field was introduced as the only way to link related locales together when the Internationalization (i18n) plugin is enabled.
  • Getting all or some specific locales is possible using the localizations field with API calls.

In Strapi 5

  • The localizations field does not exist anymore.
  • It's not possible anymore to get all versions of a document in all locales with a unique query.
  • Other edge use cases might not be possible any more either (see notes).

Migration​

This section regroups useful notes and procedures about the introduced breaking change.

Notes​

  • It's not possible anymore to populate all localizations such as in the following Strapi v4 code example:

    // Populate all locales of each document
    strapi.entityService.findMany('api::articles.articles', {
      populate: { localizations: true }
    })

  • It's not possible anymore to use a localizations filter such as in the following Strapi v4 code example:

    // Find entries that have a french locale
    strapi.entityService.findMany(articles, {
      filters: {
        localizations: {
          locale: 'fr'
        }
      }
    })

  • It's not possible anymore to create a complex filter based on localizations. For instance, in the following Strapi v4 use case, you could return English-localized versions only for entries who had a French-localized version:

    await strapi.entityService.findMany({
      filters: {
        locale: 'en' // Get entries that are in English
        localizations: {
          locale: 'fr' // Make sure the entry has another related French one
        }
      }
    })

  • Similarly, it's not possible anymore to get entries in a specific locale by filtering out entries who have another locale, such as with the following Strapi v4 code:

    await strapi.entityService.findMany({
      filters: {
        locale: 'en' // Get entries that are in english
        $not: {
          localizations: {
            locale: 'fr' // Make sure the entry does not have another related French one
          }
        }
      }
    })

Manual procedure​

Based on your custom code, you might need to use workarounds in Strapi 5 to get feature parity with Strapi v4.

The Document Service API now returns only a given locale version of document(s), such as in the following example code:

strapi.documents('api::articles.articles').findMany({ locale: 'en' })

If you need to get all locales of a single document, or multiple locales of many documents, you should resort to using the Query Engine API, because the locale attribute exists in the database.

Additional information about how to use the locale parameter can be found in the Document Service API reference documentation.