documentation icon indicating copy to clipboard operation
documentation copied to clipboard
verified publisher icon strapi

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

Open kennethzuniga opened this issue 7 months ago • 1 comments

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:

  1. Whether filtering by multiple locales is officially supported.
  2. If the OR logic is reliable and safe to use in production.
  3. 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).

  • If the behavior is not supported or not recommended, document this limitation and suggest alternative approaches (such as sending multiple requests or creating a custom controller).

Related issue(s)/PR(s)

No response

kennethzuniga avatar Jun 03 '25 20:06 kennethzuniga

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

⚠️ Note: This response may not be completely accurate. Please verify the information.

Hi there! Thank you so much for taking the time to raise this thoughtful and detailed issue. We really appreciate your effort to clarify the behavior around filtering by multiple locales in the REST API with the i18n plugin—this kind of feedback is invaluable for improving both Strapi and its documentation.

Addressing Your Questions:

After reviewing the official Strapi 5 documentation, I want to provide you with the most accurate information available:

  • The documentation currently describes filtering by a single locale parameter, for example:
    /api/articles?locale=fr
    This is the documented and officially supported way to filter content by locale using the REST API. The docs do not mention support for passing multiple locale parameters in a single request, nor do they describe the behavior you observed (e.g., /api/articles?locale=en-US&locale=es-ES) REST API: locale.

  • There is no explicit documentation stating that multiple locale parameters are supported, nor is there an example or guarantee of OR logic when using them. The official guidance is to specify a single locale per request. In fact, with Strapi 5, the ability to use locale=all to fetch all locales at once has been removed, and the recommended approach is to make separate requests for each locale you need Breaking change: no locale=all.

  • If you need to fetch content in several locales, the documented and supported method is to:

    1. List all available locales in your app.
    2. Make a separate request for each locale you want to retrieve.

Example:

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

This approach is recommended to ensure stability and future compatibility.

What about the current behavior you observed?

While you may see that passing multiple locale parameters currently returns content from both locales, this is not documented or guaranteed to be supported. It could be an unintended side effect of the underlying query parsing, and relying on it may lead to issues if the behavior changes in a future release. For production applications, we strongly recommend following the documented approach and not depending on undocumented features.

Next Steps & Suggestions:

  • If you feel that official support for multiple locales in a single request would be valuable, we encourage you to submit a feature request or upvote existing ones at Strapi Feedback.
  • If you believe the current behavior is a bug or could lead to confusion, please let us know, and we can flag this for the core team (@pwizla) to review for possible clarification or correction in the codebase or documentation.
  • For further discussion or to connect with other community members and the Strapi team, feel free to join our Forum or Discord.

Thank you again for your attention to detail and for helping make Strapi better for everyone! If you have any more questions or need further clarification, please let us know—we’re here to help.

📚 Relevant documentation:

ℹ️ 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.

💡 For feature requests or product feedback, visit feedback.strapi.io.

github-actions[bot] avatar Jun 04 '25 16:06 github-actions[bot]

Closing, considering the original poster's 👍 emoji reaction to the answer above as an approval 😊 If you need further help or feel this issue is unresolved, feel free to reopen it

pwizla avatar Jun 30 '25 09:06 pwizla