Language handling in OGC API Records

[pvretano]

This purpose of this issues is to capture discussion/requirements/etc. for language handling in Records. A starting point can be the language discussion from features which, presumably, will eventually make it into OGC API Common. Please feel free to add discussion/requirements/etc. to this issue.

[pvretano]

JOINT OGC OSGEO ASF Sprint 2021: @pvgenuchten @kalxas & @pvretano discussed language handling in records. The basic question is how does one get records (i.e. tiles, description, etc.) in a specific language. These were the points discussed:

1. The basic approach is to use HTTP language negotiation via the Accept-Language header.
2. Client lists languages in preferred order and server responds with first one that is available or only language it has if none are available.
3. @pvgenuchten mentioned that one requirement would be to get all the languages in a single response.
4. @pvretano mentioned that perhaps a special Accept-Language token for "all languages" or if the the Accept-Language header is not present that response with ALL languages. (@pvretano I believe '*' means any language so that would not do in this case)
5. @pvretano pointed out that the problem with this approach is that the record schema would need to be significantly restructured to allow arrays of internationalised strings similar to what is done by OGC in the XML schemas.
6. After some discussed an emerging consensus was to handle languages the way we handle output formats. That is, client negotiates a specific language and server responds accordingly. However, the server also includes links in the links section to get the record in the other available languages. In each link, the language is indicated using the hreflang key. The server, as is the case in features, would need to implement a mechanism for requesting a specific language in an embedded link (e.g. perhaps a lang= query parameter, although the exact method is left to the implementation).

Example:

{   
    "id": "id73",
    "type": "Feature",
    "geometry": { ... },
    "properties": { ... },
    "links": [
       {  
          "title": "JSON Έγγραφο στα ελληνικά",
          "href": "http://www.someserver.com/ogcapi/mycat/items/10?lang=el&f=json",       
          "rel": "related",
          "type": "application/geo+json",
          "hreflang": "el"
       }, 
       {  
          "title": "JSON Document en grec",
          "href": "http://www.someserver.com/ogcapi/mycat/items/10?lang=fr&f=json",       
          "rel": "related",
          "type": "application/geo+json",
          "hreflang": "fr"
       },...
    ]
}

Final note, there might some use of templated link here too ... to prevent combination explosion.

[pvretano]

22-FEB-2021: The general sense of the SWG is that the description above is OK. Multiple language responses (i.e. all langs supported by a server presented all at once) was thought to be out of scope especially given that links to alternate language representations can be included in the links sections. @pvretano may add some informative text to about this in the specification. Also see issue #92 about using OPTIONS to get the list of supported languages.

[pvretano]

Added clause to specification describing language negotiation. A language associated with a resource is specified using the language key/property/field of a records. The language in with the record is presented in a response document is negotiated using the Accept-Languages header. Only one language can be requested at a time.

[pvretano]

05-MAY-2020: Verify that the discussion has already been included in the draft and then close.

[pvretano]

09-AUG-2021: The language issues are discussed in the specification. That is, resource-specific language is handled by the language parameter. The language in which the record itself is presented in a response is negotiated using standard HTTP methods (i.e. Accept-Language). So, this issue can be closed.