fulfillment language

[jspetrak]

What the documentation currently states

• some reference data is meant to be multilingual (cf carrier cards
• Zalando guidelines mention:
  • MUST use standard formats for country, language and currency properties
  • SHOULD use content negotiation, if clients may choose from different resource representations [244] (includes the use of accept-language headers)
• over errors:
  • A warning message is typically made of a code and a detail.
  • The details are not translated and the expected language there should be in English.
  • It is up to the implementers to foresee a translation based on the code if relevant. Optionally, a warning message can contain reference to resources in the model.
• in the codelist:
  • Language: Language codes used in OSDM are based on the ISO 639-1 standard. => aligned with standards
  • Language codes used in OSDM are based on the ISO 639-1 standard.

What is defined in the swagger

• an accept-language header is present in all calls (GET, POST, PATCH & DELETE). The description seems generic
• persons (purchaser & passengers) have an optional preferred language attribute

Languages as they apply in the business (benerail view)

Usually in our business, we can distinguish the following use cases where language or localised information is relevant:

• the interface language: indicates the language in which messages and localised reference data is to be returned in the interface
• The product description language: the notion is close to the interface language, but more specifically covers the language in which product conditions (sales/aftersales) are returned in the interface
• The communication language towards the booker and/or the traveller: Typically, this is the language in which confirmation emails will be sent to the booker and/or the traveller.
• The fulfillment language: this is the language in which the fulfillment documents (typically tickets) will be generated.

So, what is wrong ?

• The main issue with the current setup is that the accept-language notion is way too ambiguous to represent the various concepts listed above:
• There is today no value available to indicate the language of an existing entity
• This gives the impression that a user can “language-hop” on every call without any limitation, which is definitely not true:
  • Oftentimes, once generated, the language of a resource (a ticket for example) is fixed. A get with an accept-language different from that language would not give the expected result
  • A given provider only supports a limited set of languages, and that set can be different for ticketing and in the interface
• In some calls, there could be multiple language notions involved. the single accept-language header would in those case have to be applied to all notions

Benerail proposal

• In all cases, when the wish of the requestor cannot be fulfilled, fall-back to english with a warning message
• For communication language:
  • Option 1: add an explicit “selectedCommunicationLanguage” on the purchaser, that can be patched as other elements.
  • Option 2: use the preferredLanguage of the purchaser. Concern: The preferred language could come from a crm profile and not match any supported language => potentially ambiguous: is the preferred language of the purchaser necessarily the one to submit as the communication language ? (crm profile, booking on behalf of…)
  • Optionally: introduce a new endpoint returning the available communication language. Could be on booking level, but most likely on root level (this is probably not booking-dependent)
• For fulfillment language:
  • in all cases: add a language attribute on the fulfillment to indicate which language an existing fulfillment is in
  • Option 1: add a fulfillment language attribute on the booking. This language is used to indicate in which language. If the setting is not possible, set to english
  • Option 2: add the fulfillment language attribute in the post fulfillment call.
    • pro: seems logical
    • con: not possible to make sure which language will be used beforehand → if the requested language was not available it is too late too change, now tickets are generated and they are in english
  • optionally: Introduce a new optional endpoint in the booking, returning available fulfillment languages. This needs to be in the booking as it is likely also dependent on the booking content
• For product & interface language:
  • Option 1: everywhere relevant outside of the 2 elements above: use the accept-language header to specify language preference for interface and product
  • Possible issues:
    • some confusion likely to remain for border cases (f ex: retrieving an existing booking with accept language= “fr” but where tickets where already generated in german => interface and sales conditions could be in french but the tickets will remain in german)
    • On some systems, it may be impossible to change the interface language after booking (because the text itself, or the language setting is part of the booking file/db entity)
    • Mitigation: only allow accept language on some calls where there is no-ambiguity - but will reduce applicable cases. To be on the safe side, that could be reduced to post offers
  • Option 2: Get completely rid of the accept-language and use product & interface language as explicit values in relevant calls - To be on the safe side, that could be reduced to post offers.

[jspetrak]

CIT defines train ticket language rules - in general "should be in language of the passenger".

CIT MIRT: 6.5.3 Languages The type of ticket is to be given in the language(s) of the country of issue. If that should not happen to be English, French, German or Italian, then the information is also given in one of those languages. 21) All other details are only to be given in the language(s) of the issuing country except where the tickets are issued overseas (Africa, Asia, Australia and Oceania, North and South America) when all the other information is to be given in English. Where there is insufficient space for a second language on tickets which are small in size, such as the RCCST (see point 7.9, Plate B), the three-character acronym in accordance with Chapter 3 of UIC leaflet 918-2 will suffice as the description of the type of ticket. The CIT provides members with a translation of the most important terms used on international tickets in the main CIT and UIC languages (see Appendix 1).

[nixxus1030]

For interface we want to use the accept-header
For communication, we use one of the preferred-languages, depending on the communication type (confirmation, real time info etc)
For fulfillment, we need to discuss further

This will be placed in the documentation

[jspetrak]

I would note that Content-Language header that was mentioned today is an interesting option for setting the language af the FulfillmentDocument. However, the documentation states it is used to describe intended language audience of the document and not the actual langague of the document. It possible restricted to HTTP responses only.

[miren-josune]

Related to languages on tickets and communication to customer/retariles I´d follow CIT MIR directive as Joseph and Clemens mentioned. And as we´re currently doing.
For the rest, mostly the interface itself, English seems to me the best option. In my humble opinion.

[nixxus1030]

Accept language only where it is relevant
In addition we need to be consistent for the reference data and use the same : We probably should have a main label + translations

[nixxus1030]

So, to sum up the concrete impact on specifications:

• General elements:

  • for reference data (including places), we specifically have a translation structure, so no need for language element there
  • we do not translate errors & warnings

• For interface language, we will rely on the accept-language, but only keep it in calls where can be relevant.

  • language mismatch between requested languages and availablie languages do not lead to an error, standard fallback language is english
  • Calls where it can be removed: !! ATTENTION: THIS IS TECHNICALLY A BREAKING CHANGE
    • all reference data calls including places
    • all delete operations
    • GET /availabilities/nearby
    • GET /availabilities/preferences
    • POST /bookings/{bookingId}/cleanup
    • POST /bookings/{bookingId}/split
  • it is up to each provider to take the accept language into consideration or not, depending on internal system capabilities

• For communication language (emails etc), we refer to the purchaser preferred language, or the passenger language if possible and applicable

  • language mismatch between requested languages and available languages do not lead to an error, standard fallback language is english

• For fulfillment language,

  • Add an issue language field on the fulfillment
  • Add an issueLanguage in the post fulfillment
  • neither is mandatory (would be breaking). If omitted or not available, (one of) the language(s) of the issuing country is used as default
  • in case a language was specified but could not be satisfied (fallback to one of the languages of the issuing country, a warning is added to the response.