Improve guidelines for use of language

[JDMKSZ]

The [int-negot] and [multi-lang] rules aren't entirely clear to me.

1. If a request contains header Accept-Language: nl-BE, should the response contain always Content-Language: nl-BE, or can it return Content-Language: nl as well? Same question for nl in request and nl-BE in response.
2. [int-negot] says about the Accept-Language that "Multiple languages may be specified in order of preference". This is not in line with the standard, which says that all values in the header are to be considered of equal importance unless weights like e.g. en;q=0.8 are used.
3. Do I understand correctly that multilanguage descriptions should always be filtered by means of a lang query parameter and may never be filtered through the Accept-Language header?
4. If a response contains multilanguage descriptions, does it need to have multiple Content-Language response headers with the different languages it has? I suppose not?
5. [int-negot] says "The Content-Language response header MUST be used to indicate the language used in the response for internationalized content.". I suppose that's true even if no Accept-Language header is given? So if an error message is returned in English, it should always have a Content-Language: en response header, even if the system never provides translations of these error messages?

[pvdbosch]

yes, some clarifications may be in order.

I believe best practice of being accepting as a server, and precise as client, should be followed. So:

1. yes; but clients would do best to specify both in request header
2. Indeed, we should indeed recommend the "q" param for importance
3. the idea is indeed to have either multilanguage representation (with optional "lang" query param filtering), or single-language with optionally choice determined by Accept-Language/Content-Language
4. and 5. I think we can update the rule with the description from the RFC:

The "Content-Language" header field describes the natural language(s) of the intended audience for the representation.

If no Content-Language is specified, the default is that the content is intended for all language audiences. This might mean that the sender does not consider it to be specific to any natural language, or that the sender does not know for which language it is intended.

• also update link to latest version of standard https://datatracker.ietf.org/doc/html/rfc9110#name-accept-language

[pvdbosch]

I'll work out a PR with clarifications on this in the guide

[pvdbosch]

PR #246 ready for review

[pvdbosch]

Added clarification that content-language can be used without language negotiation (with possible multiple langs then). Also changed to allow language from user profile (to be discussed). This was triggered by reading this: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Content_negotiation#the_accept-language_header ; but I think this page is more focused on end-user HTTP/HTML than REST APIs.

[pvdbosch]

changes are published