Documentation bug in request.acceptsLanguages
dotnetCarpenter opened this issue · comments
In the documentation (express 4.x) for req.acceptsLanguages, it states that:
Returns the first accepted language of the specified languages, based on the request’s Accept-Language HTTP header field. If none of the specified languages is accepted, returns false.
However, the code path delegates this call to jshttp/accepts which returns all requested languages from the Accept-Language HTTP header field.
We currently depend on this behavior to get the client's first language (we of course guard against * and missing header) from a request.
It appears to be equivalent for version 5.x: https://github.com/expressjs/express/blob/5.x/lib/request.js#L174
Can we please correct the documentation? I'm also afraid that this could break our use-case in the future, since returning false if no language argument is supplied will break our implementation.
PS. We can currently handle an empty array but not false. Using express 4.18.2
Hello, and thank you for the report! I was taking a read over your comments and I think I'm lost, I'm really sorry. Taking a look at the docs and the code, it seems to state what it is doing already, that is when the API req.acceptsLanguages(lang [, ...]) is called, it will take the argument languages and compare to the incoming Accept-Language header and then it returns the first matching language, otherwise false. I'm sure I'm missing something here, but I'm not sure what exactly it is. Maybe if you could explain in a different way, or even maybe if you could provide what you believe the documentation should say?
Ok, let me re-phrase to how the documentation should read:
req.acceptsLanguages([lang, ...])
Returns all requested languages, if called with no argument or with a lang argument, returns the first accepted language of the specified languages, based on the request’s Accept-Language HTTP header field. If none of the specified languages is accepted, returns false.
For more information, or if you have issues or concerns, see accepts.
@dougwilson does that make sense?
@dougwilson will you accept a PR with the change in #1401 (comment)?