Web Services Internationalization (WS-I18N)

1 Introduction

Web services technology provides application-to-application communication over the Internet. The W3C's Web Services Glossary [WSGlossary]describes a Web service as:"a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL). Other systems interact with the Web service in a manner prescribed by its description using SOAP-messages, typically conveyed using HTTP with an XML serialization in conjunction with other Web-related standards."

Most programming languages and operating environments use an internationalization model that assumes that the user's preferences (generally embodied as something called a 'locale') are maintained by the operating environment. Traditional Web technologies such as .Net or J2EE provide proprietary ways to exploit this international support in Web applications.

Web services aim to be an interoperable means of invoking logic over the Web. Implicit in the definition above is that by using standards for data representation, Web services avoid exposing the underlying implementation.

One way that Web services promote interoperability is by providing for service composition. That is, different features can be applied to the same service without modifying the service itself. For example, a service can reference both the WS-Secuirty and WS-ReliableMessaging standards without the two standards having to consider the ramifications of the other.

While these features make Web services a compelling solution to the problem of composite enterprise app development, they also present a problem for Web service internationalization: Web services are open and standards based. Existing internationalization models are closed and proprietary.

How can Web services have both internationalized behavior and platform neutral interoperability?

The W3C I18N Working Group has recently published a Note [1] that discusses this problem in detail. Requirements based on the findings in this note were used as inputs to a new draft charter for the Internationalization Core Working Group [2].

Creating a non-proprietary internationalization model actually requires very little standardization. The Internationalization Working Group believes that this work includes:

• Standardized identifiers for locale and other international preferences, such as collation.
• Standardized SOAP and WSDL descriptions (described as features) for invoking internationalized services and passing international preferences to them.
• A way of describing the deployment, implementation, or invocation policy of a service.

Consider an example of a simple Java method converted to a Web service. For simplicity we'll write a little "internationalization demo" that converts a date to a human-readable string. Here's how such a method might be implemented:

public static String getDateString(Date date) {
   if (date == null) date = new Date();
   DateFormat df = DateFormat.getDateTimeInstance(DateFormat.LONG, 
      DateFormat.MEDIUM);
   return df.format(date);
}

In this example, a Date object is formatted as a String using the default locale of the JVM where the program is executing. The locale setting of this method is not part of the service's signature and wouldn't appear in parameter list necessary for invoking this method.

This method does require some modifications if we wish to use it in a distributed setting, say a J2EE program:

public static String getDateString(Date date) {
   if (date == null) date = new Date();
   Locale userLocale = request.getLocale();
   DateFormat df = DateFormat.getDateTimeInstance(DateFormat.LONG, 
      DateFormat.MEDIUM, userLocale);
   return df.format(date);
}

The change to the method's implementation is minimal: the developer must know to get the locale from the HTTPServletRequest object, in this case. Note that a comparison with C# is instructive: there is no need to change code in .NET, since the service provider sets the thread "culture" (the Microsoft equivalent of a locale) from the request.

Now there is something mystical about how both the J2EE and .NET systems got the locale into the method. The Java proprietary Locale object was set in the Request object by processing the user's HTTP Accept-Language header and doing some (proprietary) mapping to Java's representation (the Locale object). The locale can then be accessed by a Java program. The same thing happens in forming the "default thread culture" in .NET.

Both of the examples above produce localized behavior using information maintained by the application's environment. The developer may need to do something in the body of the code to access this capability (as in the second example), but the method signature remains the same.

It is important to recognize that changing the method signature to get localized behavior is a poor implementation choice. It not only exposes the platform's implementation, but it requires the service author to create gallons of unusual code:

public static String getDateString(Date date, String locale) {
   if (locale == null) locale = "";
   if (date == null) date = new Date();
   Locale userLocale;
   if (locale.length()==0) {
      userLocale = Locale.getDefault();
   } else {
      // parse string locale and create a Locale object, 
      // about 20 to 50 lines of code.
   }
   DateFormat df = DateFormat.getDateTimeInstance(DateFormat.LONG, 
      DateFormat.MEDIUM, userLocale);
   return df.format(date);
 }

The example method shown above also requires intervention by the developer on several levels. For example, if the developer wants to use IANA language identifiers for the string parameter 'locale', then the WSDL needs to specify the type xsi:language. Furthermore, differences in system capability and identifier standardization may result in unusual results from the service.

This suggests that Web services requires rather more attention to an "internationalization model" than traditional Web content.

The W3C Internationalization Working Group is currently developing a new charter that includes work items to address the basic problem of internationalization in Web services. This work is critical to the future internationalization of Web services. This document aims to provide a framework so that this work can proceed as quickly as possible to implementation.

A "WS-Internationalization" should provide semantics so that identifiers are as clear and platform neutral as possible. There should be the possibility of vendor specific extensions so that vendors can leverage platform extensions. Ideally the identifiers should take the form of URIs. URI's provide a number of useful properties, which include the ability to retrieve resources and to define namespaces.

Internationalization Patterns

When a Web service is deployed, there are four basic patterns for how its various aspects may be internationalized:

1. Locale Neutral. Most aspects of most services are not particularly locale affected. These services can be considered "locale neutral". For example, a service that adds two integers together is locale neutral.
2. Data Driven. Aspects of the data determine how it is processed, rather than the configuration of either the requester or the provider.
3. Service Determined. The service will have a particular setting built into it. As in: this service always runs in the French for France locale. Or, quite commonly, the service will run in the host's default locale. It may even be a deployment decision that controls which locale or preferences are applied to the service's operation.
4. Client Influenced. The service's operation can use a locale preference provided by the end-user to affect its processing. This is called "influenced" because not every request may be honored by the service (the service may only implement behavior for certain locales or international preference combinations).

Each of these patterns may apply to a service or an aspect of the service. By describing the "international policy" separately for a service or sevice aspect, different end-points or bindings of the same service can provide different locale-affected behavior or different localizations. Or the logic might differ in a culturally sensitive manner.

Once one posits services that can be locale-affected and which obey policies in their Web service descriptions, it is a short journey to composing a service's international constraints and capabilities with other features. For example, a service might be provisioned so that specific binding return messages in a specific language. Or the processing rules might differ based on the language requested.

1.1 Requirements

2 Notation and Terminology

This section specifies the terminology used throughout.

http://www.w3.org/International/ws/i18n

http://www.unicode.org/reports/tr35

http://www.unicode.org/cldr/dtd/1.2/ldml.dtd
http://www.unicode.org/cldr/dtd/1.2/ldmlSupplemental.dtd

3 Data Structure for SOAP Documents

SOAP documents that need to send international preferences may reference the SOAP Feature described by this document and include the <international> block in an additional header. When sent from the requester to a provider, the header represents the preferences of the requester or its client application. When sent in a response message from the provider, the header represents the settings that the service used to process the request.

<ws-i18n:international S:mustUnderstand="..." S:actor:"...">
   ...
</ws-i18n:international>

<locale>http://www.example.org/locale/common/main/de_CH.xml</locale>
<locale value="de-CH" />
<locale value="neutral" />

<tz>GMT-0300</tz>
<tz>America/Los_Angeles</tz>

<ws-i18n:preferences>
   <ldml:measurementSystem type="metric" />
</ws-i18n:preferences>

<ws-i18n:preferences>
   <ldml:date>
      <ldml:calendar type="gregorian">
         <ldml:dateFormats>
            <default type="medium" />
         </ldml:dateFormat>
      </ldml:calendar>
   </ldml:date>
</ws-i18n:preferences>

<ws-i18n:international>
  <ws-i18n:locale value="en-US />
</ws-i18n:international>

<ws-i18n:international>
  <ws-i18n:preferences>
    <ldml:alias source="en_US" />
  </ws-i18n:preferences>
</ws-i18n:international>

<ws-i18n:international>
   <ws-i18n:locale value="en-US />
  <ws-i18n:preferences>
    <ldml:alias source="de_DE" />
  </ws-i18n:preferences>
</ws-i18n:international>

4 Data Structure for WSDL Documents

WSDL documents describe the capabilities and configuration of a service. In order to facilitate international operation, the Web service description may need to include information about how the service is deployed, allow separate bindings with different behavior, and describe the fields used by a service to activate international functionality.

WSDL introduces an additional concept to those included in the SOAP Feature, that of a service "policy". A service policy may be a concrete value ("this service executes in the French-for-France locale"), or it may be one of these:

• $neutral: This service or service attribute is locale neutral in its execution. Specific settings in a received WS-I18N header will generally be ignored by the service, although the Provider may use them (for example in the generation of fault messages).

• $user: This service or service attribute will attempt to use preferences included in a received WS-I18N header. If possible the actual value(s) used by the service will be returned in Out messages in a WS-I18N header.

• $default: This service or service attribute will use the default locale,language, or settings where it is deployed, which may be unknown at the time that the WSDL is generated (or which may vary depending on the endpoint and binding selected). The service may ignore any specific settings in a received WS-I18N header, although the Provider may use them (for example in the generation of fault messages). If possible the runtime value(s) used will be returned in Out messages in a WS-I18N header.

The WSDL file MAY specify the use of WS-I18N in a transaction as a WSDL Feature. A WSDL Feature merely indicates that the Providers will recieve and process a WS-I18N header and doesn't imply anything about the specific operation of the service.

The policy that governs the operation of a particular service is implemented as a WSDL Property:

<definitions targetNamespace="http://example.com/example"
     xmlns:ns1="http://example.com/example">
  <interface name="ns1:Thing">
    <!-- All implementations of this interface must be locale-aware -->
    <feature uri="http://www.w3.org/International/ws/i18n"
             required="true"/>
    <operation name="someOperation">
      <!-- This operation uses the $user policy -->
      <property uri="http://www.w3.org/International/ws/i18n"
               required="true">
         <constraint xmlns:locale="http://www.w3.org/International/ws/i18n">
            locale:$user
         </constraint>
      </property>
      ...
    </operation>
      ...
    <operation name="anotherOperation">
      <!-- This operation uses a specific locale -->
      <property uri="http://www.w3.org/International/ws/i18n"
               required="true">
         <value>http://example.com/myLocale#fr-FR</value>
      </property>
      ...
    </operation>
  </interface>

5 Examples

Here are some document examples:

<ws-i18n:international>
  <ws-i18n:locale value="en-US />
  <ws-i18n:tz>America/Los_Angeles</ws-i18n:tz>
  <ws-i18n:preferences>
     <ldml:alias source="de_CH" />
     <ldml:collation type="phonebook" />
  </ws-i18n:preferences>
</ws-i18n:international>