Update languge handling based on discussion with STAC.

[m-mohr]

Hey @pvretano. Any thoughts from your side regarding the comments above? I'd love to release the STAC extensions in the next days.

[m-mohr]

@pvretano I've created an OpenAPI document for the STAC extension that defines the headers and parameters more in detail, feel free to port over whatever you think is useful for you: https://github.com/stac-api-extensions/language/blob/main/openapi.yaml

Another question came up when defining the OpenAPI: What is prioritized when both the language parameter and a accept-language header is provided? query paremeter or header?

[m-mohr]

@pvretano Sorry, I don't want to nudge you by any means, but it would be very helpful for the STAC API work around languages if we could align our work until the 29th of March as I have to release until then. Thanks in advance.

[pvretano]

@m-mohr my appologies ... keep getting distracted with other stuff. I will have reviewed your comments and made adjustments before the end of the week. Please stand by ...

[m-mohr]

Thanks for the updates.

Another question came up when defining the OpenAPI: What is prioritized when both the language parameter and a accept-language header is provided? query paremeter or header?

@pvretano Any thoughts on this?

[cportele]

Another question came up when defining the OpenAPI: What is prioritized when both the language parameter and a accept-language header is provided? query parameter or header?

I would not specify this, this should be up to the server.

[m-mohr]

Thanks for your thoughts via e-mail, @pvretano. I think I lean towards prioritizing the query parameter as it's a bit more explicit due to the fact that software (e.g. a web browser) may indeed insert/inject a header that the user is not aware of. But that's the only reason, otherwise I guess it's also fine to leave it up to the implementation. Maybe it's up to the implementation with a recommendation towards the query parameter due to the reason above?

[m-mohr]

I've added a note:

Note: If both the header Accept-Language and the query parameter language are provided by a client, it is recommended to use the values provided in the query parameter. This is recommended to avoid issues with some clients (such as a web browser) that may send headers that are not under control of a user. Ultimately, it's up to the implementation to decide which source it prioritizes.

Thanks, Peter. I've published the STAC extension now.

[cnreediii]

One little nit: Chinese street signs, calligraphy, and some business cards and personal letters are use a vertical direction

[m-mohr]

@cnreediii On the other hand, the dir was inspired by HTML, which I assume is stable and well-designed. And their dir tag just allows ltr and rtl (and auto), but nothing in vertical direction.

[m-mohr]

Right now this PR conflicts the the corresponding STAC extension due to the different default values of dir. The addition of btt and ttb is not so much of an issue, but the different default value will lead to a conflicting default behavior. The default in STAC is ltr. Not sure about a path forward yet, so just stating it here for now.

[pvretano]

Right now this PR conflicts the the corresponding STAC extension due to the different default values of dir. The addition of btt and ttb is not so much of an issue, but the different default value will lead to a conflicting default behavior. The default in STAC is ltr. Not sure about a path forward yet, so just stating it here for now.

@m-mohr isn't auto a safer default?

[m-mohr]

@pvretano If the tooling can handle auto-detection, probably. But I'm not sure that's something we can expect.

[pvretano]

@m-mohr we are not specifying how the client does auto detection. auto just means that the client has to figure it out.

The client can -- for example -- simply assume ltr and go with that. More sophisticated clients can do more ... use the Content-Language header and use internal knowledge to set the direction OR look up the language code and get the direction, etc. The point is that auto simple means "You figure it out'".

[m-mohr]

@pvretano Yeah, and I think that's not a good idea. "auto" means data providers get lazy and just use it always, because why should they bother. Client Implementations can become much simpler though if auto is not in place. It's not really more work for providers to just explicitly set the corresponding value if there's a need for it. Setting a value is just much simpler than detecting the direction from the values (which values to start with?). I know how to set the dir value, but I don't know how to detect ttb or rtl text, do you? :-)

[pvretano]

@m-mohr I agree with your points but they equally well apply to just making ltr the default too ... no? Is your comment implying that we should not set a default and instead simply make dir required and force data providers to set the direction? I'd be OK with that too.

[m-mohr]

@pvretano

I agree with your points but they equally well apply to just making ltr the default too ... no?

I don't think so. There is a difference:

• If an implementer specifies "ar" (Arabic) without a dir (default: ltr), it's just wrong.
• If an implementer specifies "ar" without a dir (default: auto), it defaults to a (likely) very complex implementation.

Arguably, ltr as default might be biased due to our "western" viewpoint, but it's statistically the direction most people on Earth use. So with ltr as default you are forced to specify the direction if it's not the "most used" ltr and you don't default to the "most complex" value (auto).

My main point here is: "auto" is not needed, please remove it. It's very complex implementation-wise for clients although it's very simple to specify an explicit value as you'll very likely know in advance which language your output is in and thus you can just set it.

Is your comment implying that we should not set a default and instead simply make dir required and force data providers to set the direction?

I did not imply it, but the open question indeed is: If we don't set "auto" as default, what is the default or should it be required? I'm not sure about it. When writing the STAC extension ltr seemed obvious after checking how many languages/people use rtl vs ltr. Using the most common direction as default seemed reasonable and leads - in average - to less JSON. The (only reasonable?) alternative seems to be to make it required. Records only had the code included at the time of writing the extension though and the dir and names/titles are likely not used in all use cases, Thus, I thought requiring it might be too much to ask for.

So after thinking more about it while writing this response, I think the default ltr is the best choice.

[cnreediii]

Language direction appears to be the new CRS :-) Not trying to stir the discussion even more . . . Anyway, I just quickly reviewed the W3C HTML dirlang web page ( https://www.w3.org/TR/html401/struct/dirlang.html). Gets interesting when resolving conflicts with UNICODE and even more interesting when various RFCs are considered. Anyway, why not just use what the W3C specifies for use in HTML and use the conventions that also deal with UNICODE, MIME, and MAIL? Sorry if I am jumping in way late on this discussion.

[m-mohr]

My initial proposal was based on HTML dir (as far as I understand), except that I added a default value while for HTML it is undefined.

[cnreediii]

@m-mohr Thanks for the clarification. Should have read the entire thread :-)

[pvretano]

@m-mohr @kalxas I made the default direction ltr and added a description that basically says that ltr is the default because that is the most common case. I also said that care should be taken to set dir appropriately if your language directions is not ltr. Pleave review. If you are OK with the changes then I will merge this PR.