Web Services Internationalization (WS-I18N)

1 Introduction

Web services technology provides application-to-application communication over the Internet. The 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 a [Definition: locale: a collection of settings associated with a specific language, country, or market]) are maintained by the operating environment. This model has been extended to Web-based applications by having Web servers infer their internal locale from the user agent's Accept-Language header ([RFC3282]) or from some form of user identity management.

Web services aim to be an interoperable, platform-neutral means of invoking logic over the Web. Implicit in this is the assumption that Web services can avoid exposing the underlying implementation or encumbering the requester with knowledge of the provider's or service's implementation detail. Neither Accept-Language nor user identity is appropriate for the internationalization of Web services.

A conforming implementation will:

Identify whether a service is locale-affected in the Web Service Description.
Identify the specific locale or locale-policy used by a provider or service in the Web Service Description, including the ability to request that the user specify the locale.
Accept the specific locale and language preference(s) of the requester.
Optionally identify the specific locale or language preference(s) used by the provider or service in a response.

This specification provides semantics for the identification of international preferences which are as clear and platform neutral as possible, while providing for implementation specific extensions that leverage specific platform capabilities.

1.1 Internationalization Patterns

When a Web service is deployed, there are four internationalization patterns that can be applied to the service:

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.
Data Driven. Aspects of the data determine how it is processed, rather than the configuration of either the requester or the provider.
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.
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 service 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.

Service composition may be affected by the policy applied to that service. A service might be provisioned so that a specific binding returns messages in a specific language. Or the processing rules might differ based on the language requested.

1.2 Requirements

The goal of this specification is to enable applications to gather information about a service's capabilities from the Web Service Description; pass international preferences to Web services that the application invokes via SOAP; and understand the format and language of any messages returned.

This requires the following capabilities in Web service description (WSDL) files:

Indicate the settings that a service will use when invoked. This may include a specific setting or settings. It can also be a "policy" that solicits information from the client that invokes the service.
Indicate the structure that clients may use to activate internationalized and localized features.
Indicate the information or structure that a client may expect to receive about how a service will be executed in an optional response.

The following capabilities are required in SOAP messages:

Indicate the locale and/or language preference of the client to the Web service and service provider.
Indicate the time zone of the client.
Indicate additional optional information about the client's international preferences.
Provide an extensible mechanism for adding other related information to the request.

2 Notation and Terminology

This section specifies the terminology used throughout.

2.1 Notation and Terminology

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

2.2 Namespace

The XML namespace URI that MUST be used by implementations of this specification is:

http://www.w3.org/2005/09/ws-i18n

The namespace prefix used in this document for this URI is "i18n".

The XML namespace URI for Locale Data Modeling Language [LDML] referenced by this specification is:

 http://unicode.org/cldr/

The namespace prefix used in this document for this URI is "ldml".

3 Data Structure for SOAP Documents

SOAP documents that need to send international preferences SHOULD reference the SOAP Feature described by this document and include the <international> block in a 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.

3.1 The International Element

The <international> element encloses the header block that provides a mechanism for attaching international preferences and contextual information to a SOAP document targeted at a specific receiver (SOAP actor). The block can, therefore, be repeated multiple times in a SOAP message.

A message MAY have multiple <international> header blocks if they are targeted for separate receivers. However, only one <international> header block can omit the S:actor attribute and no two <international> header blocks can have the same value for S:actor. International preference information targeted for different receivers MUST appear in different <international> header blocks. The <international> header block without a specified S:actor can be consumed by anyone, but MUST NOT be removed prior to the final destination as determined by [WS-Routing].

Note: In practice, the <international> block is rarely repeated in a header. The main case for repeating it is when an intermediary service is forwarding a request. See Section 4.7 of [I18NScenarios].

Sub-elements of <international> can appear in any order.

Example 1: Sub-elements of international

<i18n:international S:mustUnderstand="..." S:actor:"...">

   ...

</i18n:international>

3.2 The Locale Element

The <locale> element MUST appear exactly one time in the <international> block. It represents the requested user locale, the value of which is expected to be described by Language Tags and Locale Identifiers (work in progress in the Internationalization Core Working Group). The contents of the element MUST be either a valid RFC3066bis [RFC3066bis] (or its successor) language tag or one of the policy values "$neutral" or "$default".

The value $neutral represents the base or root locale on the receiving system. Different systems and environments identify this setting in different ways:

System	Locale
UNIX	C/POSIX
Java	Locale("","")
.NET	Invariant Culture

The value $default indicates that the service or Provider should use its own runtime locale as the base setting. This is the equivalent of saying "don't care".

Here are some examples:

Example 2: Examples of locale values

<locale>en-US</locale>      <!-- U.S. English -->

<locale>$default</locale>   <!-- default locale-->

<locale>zh-Hant-HK</locale> <!-- Chinese written in Traditional script for Hong Kong -->

3.3 The TZ (Time Zone) Element

The <tz> element MAY appear at most one time per <international> block and represents the local time zone of the Requester or Provider. The contents of the element must be either RFC 822-formatted zone offset [RFC822] or an Olson ID [tzinfo] from the 'tzinfo' database. Note that RFC 822 zone offsets are not complete time zone identifiers and Olson identifiers should be preferred.

For example:

Example 3: The tz element

<tz>GMT-0300</tz>

<tz>America/Los_Angeles</tz>

3.4 The Preferences Element

The <preferences> element MUST appear at most one time per <international> block. The <preferences> block represents a way to construct specific international preferences and overrides. It does so either by starting with a predefined locale structure and modifying only the data associated with it that is of interest to the end user, or by communicating specific value information.

Support for the <preferences> element is OPTIONAL and specific behavior in relation to any particular preference is implementation defined. Implementations of this specification are not required to recognize, support, or acknowledge the <preferences> element or any of its sub-elements. Services MUST NOT require a <preferences> element be sent in order to operate correctly.

For example, the user might wish to have a slightly different date format or use a different measuring system. The <preferences> block MAY contain any number of elements using the LDML markup language.

Examples:

Example 4: The preferences element

<i18n:preferences>

   <ldml:measurementSystem type="metric" />

</i18n:preferences>

<i18n:preferences>

   <ldml:alias source="de_DE" />

</i18n:preferences>

The LDML <alias> element allows the application to specify a base locale or collection of data from the Common Locale Data Repository [CLDR] to serve as a basis for other preferences. Thus the <alias> element can be used to import a large number of settings that the remaining preferences tailor. If the <alias> element is omitted, then the <locale> element in the <international> block represents the base set of preference data.

The <alias> element does not override the <locale> element in the <international> block.

Example 5:

If the following i18n header is received and the specific preferences requested are supported, then the service should be expected to obey the locale request of U.S. English ("en-US"), but uses the German ("de_DE") collation specified ("phonebook" in this case).

<i18n:international>

  <i18n:locale>en-US</i18n:locale>

  <i18n:preferences>

    <ldml:collation>

      <ldml:alias source="de_DE" type="phonebook"/>

    </ldml:collation>

  </i18n:preferences>

</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 maybe "this service executes in the 'Asia/Tokyo' time zone"), or it may be one of these:

$neutral: This service executes in a locale neutral way. The service MAY ignore any settings in a received i18n header. However, both the service or the Provider MAY use them (for example in the generation of fault messages). This is the default value for all services that do not define i18n. Actual execution and results are dependent on service and Provider implementation.
$user: This service will attempt to use the elements of the i18n header block, such as the locale, language, and (optionally) preferences to influence the execution of the service. A service that uses this policy SHOULD define the i18n header on its Out messages and populate the header with the values actually used at runtime. Note that these values may differ from any or all requested values. Services and Providers may also ignore header elements that do not apply to their operation and outbound headers may omit any information not available to or not applicable to the service. For example, a service that sorts strings may ignore the <tz> element and an outbound header may not include that element as a result. Actual results MAY be dependent on available resources in the service or Provider.
$default: This service will use the default locale, language, or settings where it is deployed, which is unknown at the time that the WSDL is generated (or which may vary depending on the endpoint and binding selected). The service MUST ignore any specific settings in a received 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 an 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 receive 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:

Example 6: WSDL Property for operation of a particular service

<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/2005/09/ws-i18n"

             required="true"/>

    <operation name="someOperation">

      <!-- This operation uses the $user policy -->

      <property uri="http://www.w3.org/2005/09/ws-i18n"

               required="true">

         <constraint xmlns:locale="http://www.w3.org/2005/09/ws-i18n">

            locale:$user

         </constraint>

      </property>

      ...

    </operation>

      ...

    <operation name="anotherOperation">

      <!-- This operation uses a specific locale -->

      <property uri="http://www.example.com/International/ws/i18n"

               required="true">

         <value>fr-FR</value> <!-- French for France Locale -->

      </property>

      ...

    </operation>

  </interface>

5 Examples

Here are some document examples:

Example 7: Document example

<i18n:international>

  <i18n:locale>en-US</i18n:locale>

  <i18n:tz>America/Los_Angeles</i18n:tz>

  <i18n:preferences>

     <ldml:collation>

         <ldml:alias source="de-CH" type="phonebook" />

     </ldml:collation>

  </i18n:preferences>

</i18n:international>