Web Services Internationalization Usage Scenarios

2.1.1.1 Scenario Definition

A sender and a receiver wish to use Unicode encoding to transmit data between each other. This scenario provides an example of best practice.

2.1.1.2 Description

SOAP is used for XML messages exchanging data among service nodes. Because all XML [XML] processors must be able to read entities in both the UTF-8 [RFC2279] and UTF-16 [RFC2781] encodings, using UTF-8 or UTF-16 guarantees character encoding interoperability on the SOAP layer. The Character Model for the World Wide Web [CHARMOD] document describes these considerations and guidelines.

Note: WS-I: Web Services Interoperability basic profile [WSI-BP] document describes a problem about Unicode encoding and Byte Order Mark (BOM) handling.

Applies to: SOAP, SOAP interface of software systems

2.1.2.1 Scenario Definition

A sender and receiver wishes to use non-Unicode encoding. This scenario provides an example of best practice.

2.1.2.2 Description

This scenario is divided into three aspects.

1. A sender sends a SOAP message in non-Unicode encoding.

2. A receiver receives a SOAP message in non-Unicode encoding.

3. Interaction between SOAP layer and SOAP interface such as programming language, middleware, operating systems etc.

When a sender sends a SOAP messages in a non-Unicode encoding to a receiver, the receiver may not accept the non-Unicode encoding. The sender does not always accept all character encodings that may be used with XML. In order to use a non-Unicode encoding in a SOAP message, the sender needs to know beforehand whether the receiver is able to accept the non-Unicode encoding.

Receiver passed SOAP messages to programming languages, middleware, or operating systems via SOAP interface. Through the interaction of SOAP interface, code conversion from non-Unicode encoding to Unicode may happen.

XML Japanese profile document [XML-JP] describes that using non-Unicode encodings such as Shift_JIS cannot provide interoperability in information interchange.

Applies to: SOAP, SOAP interface of software systems

2.2.1.1 Scenario Definition

In SOAP RPC scenario, a requester wishes to tell the requester's language preference to the provider in order to receive SOAP fault messages in the requester's preferred language.

2.2.1.2 Description

When a SOAP fault occurs, SOAP fault messages containing natural language descriptions of the error(s) are sent back to the requester. The requester usually wants to see error messages in the requester's preferred language(s) and data format. Currently the following mechanism is available with the HTTP binding.

Accept-language: The Accept-Language request-header field restricts the set of natural languages that are preferred as a response to the request. [RFC2616]

Using Accept-language, a requester can notify a provider of the requester's language preference. A provider can then send SOAP-Fault messages in the requester's preferred language(s). If a SOAP message does not use the HTTP binding, how can a SOAP-Fault message detect the requester's language preference.

SOAP fault messages sent back contain text in natural language(s). SOAP fault messages should include xml:lang so that a requester can process SOAP fault messages based on the xml:lang identification.

Applies to: SOAP, or an extension of SOAP

2.2.2.1 Scenario Definition

Service provider needs to return fault messages in all available languages.

2.2.2.2 Description

The Service Requester sends a SOAP document containing an error to the Service Provider. The provider generates a response containing a SOAP fault. In order to provide for multi-lingual response under the current design, the provider must return all available languages. The provider cannot know what languages (resources) are installed. Most programming environments do not provide functionality that enumerates which languages are actually installed, so the service provider must request every possible installed locale in turn in order to poll whether the string is available in that language. Since resources are often sparsely populated, this suggests significant processing overhead to loop over all possible locales, loading resources in turn.

Applies to: SOAP, or an extension of SOAP

2.2.3.1 Scenario Definition

Service requester must select a matching language from the list of fault reasons returned by the service provider.

2.2.3.2 Description

The requester may be unable to (validly) match the returned text values to its current (end user) language.

<env:faultReason>
 <env:Text xml:lang="en-US">Processing error</env:Text>
 <env:text xml:lang="cs">Chyba zpracování</env:Text>
</env:faultReason>

If the requester is in locale "en-GB", then neither string will be considered a match for the current requester language preference. Although it is apparent to a human that en-US is a reasonable match for en-GB, automated processes are not permitted to make this assumption. ("en" would be a match for both "en-US" and "en-GB").

Applies to: SOAP, or an extension of SOAP

2.2.4.1 Scenario Definition

The service provider must return fault messages in all available languages, since it doesn't know the language of the requester.

2.2.4.2 Description

Many operating environments are localized into a large number of languages (for example, Microsoft supports 33 languages in 120+ locales or regional variations). SOAP Fault reason messages might become substantial in size if every language must be returned.

Applies to: SOAP, or an extension of SOAP

2.2.5.1 Scenario Definition

The service defines a language preference in SOAP Header. The service is then chained.

2.2.5.2 Description

Service "A" defines a header containing a language request field. This service is deployed.

Service "B" defines a service that includes a call to Service "A", but defines no header.

Requester calls service "B" with arguments that cause Service "A" to generate a fault. Because there is no standardized header format, Service "A" cannot generate the faultReason in the language of the requester.

Applies to: SOAP, or an extension of SOAP

2.2.6.1 Scenario Definition

FaultReason must substitute locale-sensitive data into text message.

2.2.6.2 Description

Service "A" is defined on Provider "A". A fault is generated during invocation that returns a faultReason that includes locale affected values.

• "The date provided, 12 November 2201, was too late."

• "The argument 12345.678 was too large."

• "The argument 12345,678- was too small."

How does the provider perform the substitutions?

Applies to: SOAP, or an extension of SOAP

2.2.7.1 Scenario Definition

Service Oriented Architecture Derivative Patterns One Way Message

2.2.7.2 Description

1. Service "A" is defined to receive a message from Requester "A" and deliver to Requester "B" via Service "B". An example of this would be similar to a mail server triggered by a Web service.

2. Requester "A" calls Service "A".

3. Service "B" is unable to complete its message transaction and generates a fault.

• What language does "B" return?

• Does Provider "A"'s locale influence the language returned?

Applies to: SOAP, or an extension of SOAP

2.2.8.1 Scenario Definition

SOAP message variation if http or ftp or SMTP or RMI or IIOP (difficulty deploying in a single WSDL)

2.2.8.2 Description

1. Service "A" is defined on Provider "A".

2. The administrator of Provider "A" wishes to deploy the same service on several bindings simultaneously in the same WSDL file.

• SOAP structure requires different semantics for language preference for each binding?

2.2.9.1 Scenario Definition

HeaderFault vs.Fault

2.2.9.2 Description

1. Service "A" is defined on Provider "A" and invoked by Requester "A".

2. Service generates a fault from the header. Provider "A" returns the faultReason.

3. Later Requester "A" invokes again. This time the actual service generates a fault (and presumably the faultReason).

Can a fault generated by the actual service return multiple language versions of itself? Or would the service actually generate faults only in the language that the service is running in (the environment or context of the server). If there were a "userLocale" or "userLanguage" defined in the service provider this wouldn't necessarily be an issue.

2.2.10.1 Scenario Definition

Caching affects results.

2.2.10.2 Description

1. Caching is not well described in SOAP and Web Services architecture just yet.

2. If caching is permitted and is separate from service execution and there is no standardized language negotiation mechanism, it is possible that cached responses in the wrong language could be returned.

2.2.11.1 Scenario Definition

Locale affected fault evaluation.

2.2.11.2 Description

1. Service "A" is defined on Provider "A", running in an English locale. The service requires that the value of string variable "foo" be less than "zzz".

2. Requester "A" is running in a French locale and sends a SOAP request with foo="écrit".

3. Provider "A" returns a fault, even though in French the string is "less than" the evaluated value.

2.2.12.1 Scenario Definition

Request-response versus connection-less.

2.2.12.2 Description

2.2.13.1 Scenario Definition

Peer-to-Peer faults.

2.2.13.2 Description

1. Service "A" and Service "B" are defined as "peer-to-peer" services (that is, each service may invoke the other service or be invoked by the other service).

2. Service "A" invokes Service "B", generating a fault.

2.3.1.1 Scenario Definition

A sender wishes to send data to a receiver. The sender does not know the kind of formatting conventions that the receiver is using for various types of data. This usage scenario does not raise any requirements. It provides an example of best practice.

2.3.1.2 Description

If the sender does not know the kind of formatting conventions that the receiver is using for a particular type of data, the sender has to use well-known, locale-neutral formatting conventions. XML Schema (Part 2, Datatypes)[XMLS-2] provides such such formatting conventions. Although SOAP can support various XML encodings, SOAP specifies the common data types such as SOAP encoding which is for general cases: e.g. RPC scenario for basic interoperability. SOAP encoding is based on XML Schema.

The following data types are related to date and time. They are built-in primitive types which are specified in XML Schema Part 2.

   TYPE            : EXAMPLE               
   ---------------- ---------------------------
   date            : 2003-05-31
   time            : 13:20:00
   tz              : +09:00
   dateTime        : 2003-05-31T13:20:00+09:00
   
   double          : 1267.43233E12
   decimal:integer : 2678967543233

The above data types keep interoperability from a lexical analysis perspective. When a SOAP sender sends e.g. a date to a SOAP receiver using the above date type, both sender and receiver can interpret the date lexically.

On the other hand, date is accompanied with location. For example, 2003-05-31 in Korea is not exactly the same period of time as 2002-05-31 in France, but it is the same as 2003-05-31 in Japan. Date varies by time-zone which is related to regional government and geography etc. In processing SOAP encoding or XML Schema data types, it is necessary to distinguish locale-neutral data formatting and locale-neutral data semantics. Using SOAP encoding or XML Schema ensure locale-neutral data format, but does not ensure locale-neutral data semantics.

The following example is a SOAP message in SOAP encoding. Although all of the following data are locale-neutral formatting, the context of data differs from one location/culture to another.

   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
    <env:Header>
    </env:Header>
   <env:Body>
    <c:getAvailableFlightResponse xmlns:c="http://trip.example/query">
     <c:price>123.55</c:price>
     <c:departuredate>2003-05-31</c:departuredate>
     <c:departuretime>13:30:00</c:departuretime>
    </c:getAvailableFlightResponse>
   </env:Body>
   </env:Envelope>

SOAP transactions can use SOAP encoding/XML Schema to assure that there is no ambiguity in transactions between senders and receivers in order to keep lexical analysis interoperability. Additional attributes may be needed to assure the data semantics. Detailed scenarios are described in the next section.

Applies to: Web Services in general

2.3.2.1 Scenario Definition

A sender wishes to send monetary data to a receiver. Each of the monetary amounts has a specific currency. This usage scenario does not raise any requirements. It provides an example of best practice.

2.3.2.2 Description

SOAP messages are sent to a receiver using XML schema data types such as integer, double, float, date, time etc. However, these data types may have locale sensitive semantics such as currency and location. In order to add data semantics, adding attributes is frequently used for XML messaging scenario.

   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
    <env:Header>
    </env:Header>
    <env:Body>
     <c:getAvailableFlightResponse>
      <c:price c:currency="USD">123.55</c:price>
      <c:departuredate c:location="JFK">2003-05-31</c:departuredate>
      <c:departuretime c:location="JFK">13:30:00</c:departuretime>
     </c:getAvailableFlightResponse>
    </env:Body>
   </env:Envelope>

Another option is to use a structure consisting of two elements for RPC scenario using SOAP encoding.

   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
    <env:Header>
    </env:Header>
    <env:Body>
     <c:getAvailableFlightResponse>
      <c:price>
       <c:currency>USD<c:currency>
       <c:amount>123.55</c:amount>
      </c:price>
      <c:departuredate>
       <c:location>JFK</c:location>
       <c:date>2003-05-31</c:date>
      </departuredate>
      <c:departuretime>
       <c:location>JFK</c:location>
       <c:date>2003-05-31</c:date>
      </departuretime>
     </c:getAvailableFlightResponse>
    </env:Body>
   </env:Envelope>

Applies to: Web Services in general

2.3.3.1 Scenario Definition

A sender wishes to send monetary data to a receiver. Sender and provider may use arbitrary currencies, but both sender and receiver do not use multiple currencies. They wish to set a default currency for one SOAP message.

2.3.3.2 Description

Additional attribute is frequently used for monetary data exchange as mentioned above section. The following example shows multiple currency data transmission in a SOAP message.

   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" >
    <env:Header>
    </env:Header>
    <env:Body>
     <c:purchase>
      <c:apple>
       <c:currency>JPY</c:currency>
       <c:amount>123.55</c:amount>
      </c:apple>
      <c:orange>
       <c:currency>USD</c:currency>
       <c:amount>325.78</c:amount>
      </c:orange>
     <c:peach>
      <c:currency>EUR</c:currency>
      <c:amount>36.55</c:amount>
     </c:peach>
    </c:purchase>
   <env:Body>
   </env:Envelope>

Most regional services use a default currency instead of multiple currencies. For example, Japanese internal shopping uses JPY by default. The following is an example which has the default currency in SOAP header. It is possible to specify the default currency attribute in SOAP body instead of SOAP header.

   <?xml version='1.0' ?>
   <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" >
    <env:Header>
     <WS-I18N:WSinternationalization xmlns:WS-I18N="http://example.org/2002/11/21/WS-I18N">
      <WS-I18N:Currency>JPY</WS-I18N:Currency>
     </WS-I18N:WSinternationalization>
    </env:Header>
   <env:Body>
    <c:purchase>
     <c:apple>
      <c:price>123.55</c:price>
     </c:apple>
     <c:orange>
      <c:price>325.78</c:price>
     </c:orange>
     <c:peach>
      <c:price>36.55</c:price>
     </c:peach>
     </c:purchase>
    </env:Body>
   </env:Envelope>

Although adding parameter to SOAP body requires design change for service interface, adding default value into SOAP header does not affect services interface.

Applies to: Web Services General

2.3.4.1 Scenario Definition

A sender wishes to send locale dependent data to a receiver for regional SOAP messaging or RPC. The receiver needs to process the locale dependent data correctly.

2.3.4.2 Description

If a Japanese sender sends date data to a Japanese receiver, the Japanese sender wishes to send data in Japanese calendar's date such as H13-5-31(H means Heisei era; see Appendix C Heisei) to the receiver.

   <?xml version='1.0' ?>
   <env:Header>
    <WS-I18N:WSinternationalization
       xmlns:WS-I18N="http://example.org/2002/11/21/WS-I18N">
     <WS-I18N:dataTypePreference>
      <ja:JDate xmlns:ja="http//example.org/2003/12/3/ja">EYY-MM-DD</WS-I18N:JDate>
     </WS-I18N:dataTypePreference>
    </WS-I18N:WSinternationalization>
   </env:Header>
   <env:Body>
    <departuredate>H14-5-31</departuredate>
   </env:Body>

Default is Locale neutral mode. If a sender and a receiver can handshake with each other using the same semantics of locale, sender can send a locale dependent data to a receiver, and the receiver can process the data consistently.

If WSDL can describe locale sensitive datatypes, locale negotiation mechanism can be described in WSDL. Is it applicable requirement for interface definition of WSDL?

There is a difference between data types such as telephone number, ZIP code, etc., which can be modeled as strings with patterns, and data types such as dates and numbers, where a connection with the value space (e.g. of XML Schema) may be desirable.

Applies to: WSDL, SOAP, or Localizable datatype

2.3.5.1 Scenario Definition

A service is defined using "Service Oriented Architecture Derivative Patterns Intermediary" as found in Web Services Architecture document[WSA].

2.3.5.2 Description

1. Service "A" is defined as a service that returns status text and deployed on Providers "A1", "A2", and "A3" in different language configurations (locales).

2. Provider "B" polls Service "A" on each machine and caches the results.

3. Service "B" is defined as a process that returns cached results and is deployed on Provider "B".

4. Requesters "C1", "C2", and "C3", each with different language preferences, invoke Service "B" sporadically to obtain data.

• Provider "B" must cache faults and data in all possible languages since it cannot know in advance which requesters will want what data.

• Provider "B" must send all data to each requester.

• Correlation of data may prove difficult.

2.4.1.1 Scenario Definition

Data is formatted for an end user by the receiver according to the end user's preferences and the system conventions. This usage scenario does not raise any requirements. It provides an example of best practice.

2.4.1.2 Description

The receiver may format data in order to display the data in a user interface. Locale sensitive data formatting functions are widely provided by internationalization functionality of operating systems, programming languages, or applications such as word processors and middleware. Therefore, an application can format locale neutral data using built-in internationalization functions. The details of data formatting vary across different systems. Therefore, Web services themselves do not guarantee completely identical formatting on different systems.

Applies to: Web Services General

2.4.2.1 Scenario Definition

The sender formats data for viewing by an end user on the receiver side. The sender takes care of data formatting to assure consistency of presentation.

2.4.2.2 Description

2.4.3.1 Scenario Definition

A receiver formats data according to the format provided by the sender.

2.4.3.2 Description

Data sent by a sender is formatted by the receiver according to format(s) provided by the sender. This is different from scenario 2.13 and 2.14 in that the center of decision and the actual execution of the formatting are separated. Scenario 2.13 or 2.14 should be preferred because they are more straightforward, but this scenario may be chosen for various reasons such as: The sender wants to ensure consistent appearance, and the data may be used on the receiver side both for formatting and for further processing.

Data formatting rules should be sent to receivers together with data, in order to keep consistency self-descriptively, for user interface.

The following is a pair of float data and an example of numeric formatting rule.

    Value: float: 235055.55
    Numeric formatting rule: #.##.##0,##

Presentation result for user interface is:

    2.35.055,55

The following example shows a way to send a formatting rule in SOAP header together with a float value.

    <?xml version='1.0' ?>
    <env:Header>
     <WS-I18N:WSinternationalization
       xmlns:WS-I18N="http://example.org/2002/11/21/WS-I18N">
      <WS-I18N:presentationPreferences>
       <WS-I18N:NumericFormat>#.##.##0,##</WS-I18N:NumericFormat>
       </WS-I18N:presentationPreferences>
     </WS-I18N:WSinternationalization>
    </env:Header>
    <env:Body>
     <value>235055.55</value>
    </env:Body>

Because a receiver receives a value in locale neutral decimal data together with formatting rule, the receiver can format the data for user interface self-descriptively.

Applies to: Web Services General

2.5.1.1 Scenario Definition

The service provider needs the locale of the sender in order to perform locale sensitive processing. There are three levels to this: Transport layer, service provider layer (SOAP Header), and service layer (SOAP Body) (we need separate scenarios for these)

2.5.1.2 Description

2.5.2.1 Scenario Definition

Using an opaque identifier to identify a locale.

2.5.2.2 Description

Same locale processing does not always return same result, because there are locale implementation differences among runtime environment.

A sender(requester) wishes a provider(receiver) to return a result of specific locale sensitive processing such as Java Locale, Windows Locale, or POSIX locale etc

Because user can customize locale, a sender(requester) wishes a provider(receiver) to return a result of locale sensitive processing based on the sender customized locale.

Applies to: A locale identification which distinguishes runtime differences or users customization.

2.6.1.1 Scenario Definition

Searching for Web services depending on language or culture.

2.6.1.2 Description

Repositories and search-able meta-data (such as UDDI [UDDI]) about Web services need to provide support for multiple language searches. Transport layer issues do not allow XML data structures to be used for resolution, except by reference (e.g. the receiver must down-load a separate resource asynchronously to "decode" the preference). Tags on this layer may be necessary in place of XML data structures.

2.6.2.1 Scenario Definition

There is no way for the service to find the best appropriate match when the user's request cannot be met.

2.6.2.2 Description

If the sender specified "ja-JP" and "ja-JP" is not available at the receiver, what should the fall-back schema be?

2.7.1.1 Scenario Definition

Using a Web service to obtain some locale-related service, such as formatting, collation etc.

2.7.1.2 Description

Some locale-related tasks are not easy to describe by an exchangeable data structure. Also, not all systems will have code for all locales. It may therefore be desirable in some cases to 'outsource' locale services.

Example 1: Formatting a date according to traditional Thai conventions (the full text of the formatted date is very long)

Example 2: Converting a date according to local rules that may not be predictable.

Example 3: Collation data can be very large, and collation may include additional domain-specific preprocessing in addition to the simple comparison of strings. It may therefore in some cases be more efficient to send the data to be sorted to another system.

2.7.2.1 Scenario Definition

Using Web services to update locale-related data that may change dynamically and/or in ways that are not easily predictable.

2.7.2.2 Description

Some kinds of data needed for culturally sensitive operations is not easily predictable. Web services may be used to update such data, either by polling for updates or by sending out updates.

Example: Certain calendars depend on actually observed events, such as the actual observation of the new moon.

Example: Jurisdictions once in a while may change their rules for which time-zones they are in at which time of the year.

Issues: Scalability; requests may concentrate at specific times; polling may have to be repeated over and over without any actual updates.

2.8.1.1 Scenario Definition

If a Web service starts out uninternationalized and is later internationalized, it must be re-deployed as a separate service because the original service contract has changed.

2.8.1.2 Description

The web services developer is solely responsible for supplying the fields, logic, and semantics that will be used to achieve i18n capabilities. Each service will vary in its approach and may not bother to supply a suitable mechanism. Without guidance from the client, assumptions have to be made that are unsuitable. For example, the locale of the server may be used to format the response. When the service is internationalized, the only option is to ask for locale as an additional input, changing the service contract.

There is an important functional and semantic difference between a field supplied in the actual service invocation (that is, as part of the data) and one supplied in the envelope (that is, as part of the protocol) because when supplied as part of the data, developers must always take care to create, populate, read, and process the fields. Internationalization of an existing service therefore takes the form of deploying a new service (since the inputs have changed).

By contrast, if locale and language preferences are part of the "context" (in the envelope, for example), the developer gains several advantages. First, both the provider and the service can read the locale and language preference. (The service must be provided with a specific API to obtain the locale and language from the provider, or it can be silently managed by the provider.) Services that require external environmental changes to activate their locale-sensitivity can have the provider perform this processing for them. Multiple services in the same "chain" can inherit the same locale and language context. Most important, though, the client-side environment can be optimized to provide the locale and language preferences of the end user automatically, without developers having to write code to obtain the values and populate the inputs of the Web Service. In addition, Web Service authors can add international or multi-language support to services after initial deployment without changing service descriptors (WSDL and XSD) that may already be in wide use.

2.8.2.1 Scenario Definition

There is no way for the service to communicate what language and formatting options are available.

2.8.2.2 Description

If a Web service requires that a language, locale, or formatting preference in a service description (WSDL), how can the sender know what values will have meaning at the receiver. For example, POSIX locales for a C program are very different than (say) Windows LCID values.

As a result, developers of internationalized Web services (especially those that support multi-lingual operations - that is, servers that can provide responses in a variety of human languages and dialects) have to provide the ability to external users, whose platforms and programming languages may be maximally different than their own, to know what options the service supports.

2.9.1.1 Scenario Definition

2.9.1.2 Description