How to deal with multilanguage responses?

[usapieter]

For a get educational-plan at the HvA we are currently working on, we have been asked to provide a response with the following attributes:

Studieplan omschrijving NL Studieplan omschrijving ENG

For OOA purposes, these description will be in English (of course)

I would argue that a parameter, or header that would request a specific language would the nicest option, but since the client would need both languages - this would result in two separate calls.

For now, we will implement in these way:

default language: English

description - this will return the description of the educational plan in default language description_NL - this will return the description of the educational plan in Dutch (NL)

In fact, we will add a attribute (description_NL) to the response, so no extra call is needed - and we will still maintain the OOA standard of providing the optional field.

For future cases, how would the OOA work with multi-language responses?

[joostfarla]

I see two possible solutions here:

Solution 1

The standard best practice for dealing with multi-language responses is using HTTP content negotiation. This means you can add an Accept-Language request header to pass your language preference to the server. The server will then respond with a Content-Language header to define which language the server responds with. When no accept-header is passed, it could respond with the default language (which might be English). The downside of this approach is that you have to perform multiple request to receive content in multiple languages.

Solution 2

Nesting the multi-language properties. Example:

{
  "id": "some-universal-identifier",
  "description": {
    "nl": "Omschrijving in het Nederlands",
    "en": "Description in English"
  }
}

This would allow sending multiple languages in a single response. However, if this solution would be preferred, this should not be optional. We need to keep the interface uniform, so the structure of the response should be equal, for single- and multi-language implementations. In the example above, this would mean, API X sends nl, en, and fr values, API Y will only send nl. Maybe we could add the language configuration in the root call (will create a separate issue for this in a sec).

Some additional questions:

• Are there more parts of the OOAPI, where multi-language responses could be interesting?
• Do we need to support different locales? (e.g. nl-NL and nl-BE)?

[fransward]

Needs additional discussion: V3

[usapieter]

Hi Joost, all,

we have identified that most endpoints would benefit from multi-language support. However, the urgency per endpoint is not always the same.

For instance, the 'schedules' endpoint the urgency for multi-language response would be less, as the time and location are generally 'language neutral'.

For courses, educational departments, newsitems, the urgency is higher.

Different locales is not something we have encountered an actual requirement for yet - for now it's mostly (only) Dutch (NL) and English (EN) that is required.

From what we know of, we don't know any institution that makes (for example) a difference between US or UK English....or Dutch and Vlaams :)

Of course, there is always an actual implementation that needs to be carried out (in order to support multi language in an API, the system of record (source system) must have multiple languages available ) - but that shouldn't be to much of an impact on the standard itself. In the case there is only 1 language available, the API just returns that in the header (a API consumer can request "French" - but the API wil just return "Dutch" as it would the one language available).

Would it be wise to adopt a default language in the standard - or would that be up to any institution to let them decide for themselves what their default language would be (and return that for example in the meta data endpoint - see https://github.com/open-education-api/specification/issues/37).

[marcokrikke]

We've ran into the same issue where our product MyTimetable expects values available in multiple locales to be returned in one OO-API response. Our use case is the following.

MyTimetable provides change detection for timetables. In order to detect changes, the product stores all timetables (e.g. all student and staff timetables). By regularly comparing the stored state with the current state (returned by the OO-API), changes in timetables can be detected. When a change is detected, other systems are notified of this (webhooks). These notifications are multi-locale, so the receiving system can decide what locale to use (e.g. send a notification in a particular locale selected by their end user). Therefore, all information in the timetable store must be multi-locale.

When the /schedules endpoint in the OO-API only returns data in one locale and when the customer uses two (e.g. English and Dutch), we need to call the endpoint twice to get data in both locales. With 30,000 student timetables, this results in significant overhead.

We currently use the following format for localised strings in our (non OO-API) APIs:

{
    "@type": "localized_string",
    "defaultValue": "This is a localised message.",
    "localizedValues": {
        "en-US": "This is a localized message.",
        "nl": "Dit is een gelokaliseerd bericht."
    }
}

We use an implicit default locale for defaultValue and also return a map of other locales available. If a system wants to use a locale that is not specified (e.g. en-GB or fr-FR), it must use the defaultValue as a fallback. The language tags are BCP47. The @type property can be used as a hint for parsers.

Moving to localised strings in the response would of course be a breaking change to the API. For now, customers can extend the OO-API where required with the localised strings. Perhaps it would be good to come up with a generic approach to express multi locale values so that can be used in v4 of the API?

Not sure if other data types need to be localised as well, think of links to external content.

[mpdejong]

In the past months I have seen a number of developments in which OOAPI is mentioned as the preferred standard to transport information between systems. Therefor the use cases as mentioned before apply. A specific use case is the provisioning of enrolled students from a SiS to a LMS. The educational information of the courses can be multilingual and can differ from country to country.

The proposed solution number 2 by @joostfarla would fit best. The locales should also be included to support differences between countries. The locales can be helpful when aggregation of educational offerings from different countries is done of for referencing from educational content to be used in European wide MOOC's. (e.g. nl-NL; nl-BE; en-UK; en-US)

[jelmerderonde]

During the work group meeting of November 12 we decided on using the http language negotiation mechanism.

[joostfarla]

Language negotation: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

[fransward]

This issue could be closed since it is solved by adding the Accept-Language header in V4:

The OOAPI specifcation relies on the HTTP content negotiation mechanism to specify how a client can request information in a specific (natural) language, and how a server should respond to that request. In short: a client adds an Accept-Language header to their request, which the server uses to determine in what language the requested content should be returned. More information about this mechanism can be found at Mozilla MDN.