1 Basic Web Service Internationalization Scenarios
1.1 Locale Sensitive Presentation and Human Readable Text
1.1.1 Enumerated Values and Object Names
1.1.1.1 Use of Default English-like Names
1.1.1.2 Types of Names
| Editorial note: FTF | |
| Mike to provide text (Visa vs. Carte Bleu) [Owner: Mike] | |
Occiasionally, in the design of an application, there is a need to present enumerated values to an end-user to choose an option for completion of a transaction. Take, for example, an on-line purchase for travel. The credit cards, "Mastercard(r)" and "Visa(r)" have European counterparts known as "Eurocard(r)" and "Carte Bleu(r)" respectively. Each of these go through the same payment clearinghouses and are processed in the same way. It is common to see European payment sites stating that Matercard⁄Eurocard and Visa⁄CarteBleu are honored. However, outside of Europe, only the more common global brands are used.
In this example, a requester sends a user locale asks for valid payment methods to present to user. The locale would be the language of the user and the country in which the purchase is being made. The service then returns an enumerated list of accepted payment methods. The requester may have no previous knowledge of the payment methods, and so will rely on the service to provide the appropriate types to present to the user. The service will expect one of the values in the enumerated list to be returned as the payment type when completing the transaction.
From the Open Travel Alliance (OTA), we find the following valid enumeration values for credit cards:
(From http:⁄⁄www.opentravel.org⁄2004A⁄xsd⁄3⁄simpletype⁄PaymentCardCodeType.htm)
EnumerationDescription
AX American Express
BC Bank Card
BL Carte Bleu
CB Carte Blanche
DN Diners Club
DS Discover Card
EC Eurocard
JC JCB Credit Card
MC Master Card
TP Universal Air Travel Card
VI Visa
Each of these would normally be presented in a pull-down pick list, but a particular organization may wish to discard with the differences, and present the list in Europe as:
... VI Visa⁄Carte Bleu MC Eurocard⁄Mastercard ...
and in North America as:
... MC Master Card VI Visa ...
In an enumerated list, best practices dictate that there is an internal value from which actions are determined, and an external value, which is presented to an end user. In the same way, even if a service has been told what locale a requester is using, the service may want to provide alternate default display values, that can be used for debugging purposes or bilingual status or transaction displays.
Names in an enumerated list fall into three primary categories, each used for different purpose.
Display names are those which are presented to the user. A well designed system will have only the Requester generating and displaying these values. If necessary, a Requester should be able to request a set of standard localized names from a Service. Those names should be keyed to culture-neutral values that are used for communication between processes.
(from http:⁄⁄www.opentravel.org⁄2004A⁄xsd⁄9⁄complextype⁄SeatingPrefType.htm)
We'll choose a slightly different OTA example since credit card names are trademarked and don't change much from one language to another. Instead, we'll use seat selection for "Aisle", "Center", "Window".
The OTA Schema, for instance, passes strings for this value, but an end-user will want to see the values in their own language. In German, the choices would be Gang, Mitte, and Fenster. Therefore, the designer of the Service may wish to return qualified locale sensitive display names that the Requester can use for display to the end user. This is especially useful for instances where terminology or messages might change and it is not desired to update the whole requester application just to update a few terms.
<xs:attribute name="SeatPosition" type="xs:string" use="optional">
<xs:annotation>
<xs:documentation xml:lang="en">Preferred position of seat in a row,
such as Aisle, Center, Window, etc.<⁄xs:documentation>
<⁄xs:annotation>
<xs:simpleType>
<xs:restriction base="StringLength16">
<xs:enumeration value="Aisle">
<displayName xml:lang="en">Aisle<⁄display>
<displayName xml:lang="de">Gang<⁄display>
<⁄xs:enumeration>
<xs:enumeration value="Center">
<displayName xml:lang="en">Center<⁄display>
<displayName xml:lang="de">Mitte<⁄display>
<⁄xs:enumeration>
<xs:enumeration value="Window">
<displayName xml:lang="en">Window<⁄display>
<displayName xml:lang="de">Fenster<⁄display>
<⁄xs:enumeration>
<⁄xs:restriction>
<⁄xs:simpleType>
<⁄xs:attribute>
The actual enumeration value, not the displayName, would be used internally and passed from Requester to Service, while the displayName would be presented to the user interface according to locale.