[TEST] [Request]: Clarify support for multiple locale parameters in REST API filter (i18n plugin)

[pwizla]

Summary

The current Strapi v4 documentation for the Internationalization (i18n) plugin only shows how to filter content using a single locale value via the REST API. However, testing reveals that using multiple locale parameters in a single request (e.g., /api/articles?locale=en-US&locale=es-ES) returns content from both locales. This suggests that an implicit OR filter is being applied, though this behavior is not documented.

Why is it needed?

This undocumented behavior could lead to confusion for developers who assume that only one locale filter is supported per request. Clarifying this in the official documentation will help users understand:

• Whether filtering by multiple locales is officially supported.
• If the OR logic is reliable and safe to use in production.
• If using multiple requests is the recommended approach when querying content in several locales.

Additionally, if this behavior is not intended or officially supported, it’s equally important to document that clearly. Developers may assume it’s a supported feature simply because it currently works, and unknowingly build functionality around it. If such behavior were changed or removed in a future release, it could cause unexpected breakages in production applications. Proper documentation will help prevent reliance on potentially unstable or unsupported patterns.

Suggested solution(s)

Update the i18n plugin documentation to explicitly state whether multiple locale parameters are supported and how they are interpreted by the REST API.

If the behavior is supported, include an example of a request with multiple locales and describe the expected logic (e.g., OR vs AND).

Related issue(s)/PR(s)

No response

[github-actions]

👋 Hello @pwizla! Thanks for opening this issue.

🤖 I've analyzed your question and here's what I found:

Hi there! 👋

Thank you so much for taking the time to raise this thoughtful question and for your detailed feedback about the Internationalization (i18n) plugin and REST API locale filtering. We really appreciate your effort to help make Strapi better and clearer for everyone in the community!

About Multiple locale Parameters in REST API

After carefully reviewing the current Strapi 5 documentation, I want to clarify what is officially supported:

• The documentation describes using the locale parameter to filter content for a single locale at a time, for example:

  GET /api/articles?locale=fr
  

  This will return articles in the French locale only.
  See REST API: locale parameterhttps://docs.strapi.io/cms/api/rest/locale

• There is no mention in the official documentation of support for passing multiple locale parameters in a single request (e.g., /api/articles?locale=en-US&locale=es-ES). The documented approach is to specify one locale per request.

• In fact, with Strapi 5, the documentation explicitly states that it is not possible to get all localized versions of a content type with a single request (such as with locale=all). Instead, you are advised to list all available locales and request data for each locale one by one.
  See Breaking Change: locale=all not supportedhttps://docs.strapi.io/cms/migration/v4-to-v5/breaking-changes/no-locale-all

Is Multiple Locale Filtering Supported?

Based on the documentation, filtering by multiple locales in a single REST API request is not officially supported or documented. If you are seeing this behavior in your testing, it may be an undocumented or unintended side effect, and there is no guarantee it will remain stable or supported in future releases.

Recommended Approach

The recommended and documented approach is to:

1. Retrieve the list of available locales (from your Strapi admin or configuration).
2. Make separate API requests for each locale you need content for.

This ensures your application remains compatible with current and future versions of Strapi.

What Should You Do?

• If you need content in multiple locales:
  Loop through your list of locales and make a separate request for each, e.g.:

  GET /api/articles?locale=en-US
  GET /api/articles?locale=es-ES
  

• If you have custom code relying on multiple locale parameters:
  Please consider updating it to follow the documented approach, as the current behavior is not guaranteed.

Next Steps & Feedback

• If you feel that multi-locale filtering would be a valuable feature, we encourage you to open a feature request or upvote existing ones! Your feedback helps shape the future of Strapi.
• For further questions or to discuss with the community, you can also join our Discord server or check out the Internationalization documentation.

---

Thank you again for your attention to detail and for helping us improve the Strapi experience! If you have any more questions or suggestions, please let us know. We're here to help and always happy to hear from you. 😊

Warm regards,
The Strapi Team

📚 Relevant documentation:

• Document Service API: Using the locale parameter|delete() locale versions
• Documents|Documents
• REST API: locale|POST Create a new localized document for a collection type
• REST API: locale|PUT Create a new, or update an existing, locale version for an existing document
• Document Service API|findMany()
• REST API parameters|REST API parameters
• REST API: Filters|Complex filtering
• REST API: locale|GET Get a document in a specific locale
• Requests and Responses|ctx.request.query
• Document Service API: Using the locale parameter|publish() locale versions
• locale=all can not be used to get all entries in all locales|locale=all can not be used to get all entries in all locales
• Internationalization (i18n)|Usage
• REST API: Filters|REST API: Filters
• Document Service API: Using the locale parameter|Document Service API: Using the locale parameter
• REST API: locale|REST API: locale

---

ℹ️ This response was generated automatically. If this doesn't fully answer your question or if you need further assistance, please mention @pwizla in a comment and a human maintainer will help you.

You can also try our interactive AI chat for more detailed assistance.

[pwizla]

Successful test! Looking forward to the next steps 🚀