Web Services Internationalization (WS-I18N)

1.1 Internationalization Patterns

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

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.

1.2 Requirements

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

From this goal, the following functionalities are required in SOAP messages, see 3 Internationalization Data Structures for SOAP Messages:

1. indicate the locale and/or language preference of the client to the Web service and service provider;

2. indicate the time zone of the client;

3. indicate additional optional information about the client's international preferences;

4. provide an extensible mechanism for adding other related information to the request.

An internationalization "policy", see 4 Indicating Use of WS-I18N, can be used to describe the capability of these functionalities.

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 [RFC 2119].

2.2 Notational Conventions

This specification uses the following syntax within normative outlines:

• The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.

• Characters are appended to elements and attributes to indicate cardinality:

  • "?" (0 or 1)

  • "*" (0 or more)

  • "+" (1 or more)

• The character "|" is used to indicate an exclusive choice between alternatives.

• The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.

• This document relies on the XML Information Set [XML Infoset]. Information item properties are indicated by the style infoset property.

• XML namespace prefixes (see 2.4 Namespaces) are used to indicate the namespace of the element or attribute being defined.

• The ellipses characters "..." are used to indicate a point of extensibility that allows other Element or Attribute Information Items.

Elements and Attributes defined by this specification are referred to in the text of this document using XPath 1.0 [XPath 1.0] expressions. Extensibility points are referred to using an extended version of this syntax:

• An element extensibility point is referred to using {any} in place of the element name. This indicates that any element name can be used, from any namespace, unless specified otherwise.

• An attribute extensibility point is referred to using @{any} in place of the attribute name. This indicates that any attribute name can be used, from any namespace.

Normative text within this specification takes precedence over normative outlines, which in turn take precedence over the XML Schema [XML Schema 1] descriptions.

2.3 Extensibility

Within normative outlines, in this specification, ellipses (i.e., "...") indicate a point of extensibility that allows other Element or Attribute Information Items. Information Items MAY be added at the indicated extension points but MUST NOT contradict the semantics of the element information item indicated by the parent or owner property of the extension. In this context, if an Attribute Information Item is not recognized, it SHOULD be ignored.

2.4 Namespaces

This specification uses a number of namespace prefixes throughout; they are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant.

2.5 Requirements on Implementations

Certain aspects of this specification are described as implementation-defined or implementation-dependent.

• [Definition: Implementation-defined indicates an aspect that may differ between implementations, but must be specified by the implementor for each particular implementation.]

• [Definition: Implementation-dependent indicates an aspect that may differ between implementations, is not specified by this or any W3C specification, and is not required to be specified by the implementor for any particular implementation.]

3.1 Internationalization Information in SOAP

The i18n:international element information item servers as a wrapper for conveying internationalization information in SOAP. Its content model is outlined below.

(01) <i18n:international ... S:actor="...">
(02)  <i18n:locale> locale identifier </i18n:locale>
(03)  <i18n:timezone> time zone value </i18n:timezone>
(04)  <i18n:preferences ...>
(05)   LDML-based or other locale preferences
(06)  </i18n:preferences>
(07) </i18n:international>

The following describes the element information items defined in the schema outline above:

/i18n:international

This element information item encloses international preferences and contextual information, see this section for more explanation.

/i18n:international/i18n:locale

This required element information item defines the locale, see 3.2 Providing Locale Information.

i18n:international/i18n:tz?

This optional element information item defines the timezone, see 3.3 Providing Time zone Information.

i18n:international/i18n:preferences?

This optional element information item defines the locale preferences, see 3.4 Providing Locale Preferences.

/i18n:international/@S:actor

This attribute information item describes the target of the international preferences. See below for more detailed explanation.

i18n:international/@{any}

Additional attribute information items MAY be specified but MUST NOT contradict the semantics of the owner element; if an attribute is not recognized, it SHOULD be ignored.

The i18n:international element information item encloses the header block that provides a mechanism for providing international preferences and contextual information within 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 i18n:international element information items if they are targeted for separate receivers. However, only one i18n:international element information item can omit the S:actor attribute and no two i18n:international element information items can have the same value for S:actor. International preference information targeted for different receivers MUST appear in different i18n:international element information items. The i18n:international element information item without a specified S:actor can be consumed by anyone, but MUST NOT be removed prior to the final destination.

3.2 Providing Locale Information

The i18n:locale element information item MUST appear exactly one time as the first item in the children property of the i18n:international element information item.

(01) <i18n:locale> (locale identifier based on [LDML])|
(02) "$neutral" | "$default") </i18n:locale>

The i18n:locale element information item represents the locale in the web services interaction. Its value MUST be either a valid [LDML] locale identifier or one of the values "$neutral" or "$default".

The value $default indicates that the service or provider should use its own runtime locale as the base setting. The value $neutral represents the base or root locale on the receiving system. Different systems and environments identify this setting in different ways. Examples are given below.

Examples of various values for the i18n:locale information item are given below:

(01) <i18n:locale>en_US</i18n:locale>      <!-- U.S. English -->
(02) <i18n:locale>$default</i18n:locale>   <!-- default locale-->
(03) <i18n:locale>zh_Hant_HK</i18n:locale> <!-- Chinese written in
                                                Traditional script for Hong Kong -->

3.3 Providing Time zone Information

The i18n:tz element information item MAY appear at most one time in the children property of the i18n:international information item. If present, it MUST follow the i18n:locale element information item.

(01) <i18n:tz> ([RFC 822] value) | (Olson ID [OLSON ID]) </i18n:tz>

The i18n:tz element information item represents the local time zone of the requester or provider. The value of the element MUST be either RFC 822-formatted zone offset [RFC 822] or an Olson ID [OLSON ID] from the 'olsonid' database. Note that RFC 822 zone offsets are not complete time zone identifiers and Olson identifiers are preferred. It is implementation-defined whether an RFC 822-formatted zone offset or an OLson ID is given, and how a choice between these two kinds of values is indicated.

An example of the i18n:tz element information item using an RFC 822 zone offset is given below:

(01) <i18n:tz>GMT-0300</i18n:tz>
(02) <i18n:tz>America/Los_Angeles</i18n:tz>

3.4 Providing Locale Preferences

The optional i18n:preferences element information item MUST appear at most one time in the children property of the i18n:international element information item. If present, it MUST follow the i18n:tz element information item or (if i18n:tz is omitted) the i18n:locale element information item.

(01) <i18n:preferences ...>...</i18n:preferences>

The i18n:preferences element information item represents a way to construct specific locale preferences and overrides. Support for the <i18n:preferences> element is OPTIONAL and specific behavior in relation to any particular preference is implementation dependent. Implementations of this specification are not required to recognize, support, or acknowledge the i18n:preferences element information item or any of its sub-elements. Services MUST NOT require a i18n:preferences element information item be sent in order to operate correctly.

An example of the usage of i18n:preferences is given below. It describes preferences using [LDML].

(01) <i18n:preferences>
(02)    <ldml:measurementSystem type="metric" />
(03) </i18n:preferences>

The LDML alias element information item is demonstrated below as another example of the content of the i18n:preferences element information item. alias 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 it can be used to import a large number of settings that the remaining preferences tailor.

(01) <i18n:international>
(02)   <i18n:locale>en_US</i18n:locale>
(03)   <i18n:preferences>
(04)     <ldml:collation>
(05)       <ldml:alias source="de_DE" type="phonebook"/>
(06)     </ldml:collation>
(07)   </i18n:preferences>
(08) </i18n:international>

4.1 Assertion Syntax

THe i18np:i18n policy assertion consists of one element information item whose structure is defined below.

/i18np:i18n

The i18np:i18n element information item indicating the use of the mechanisms defined in 3 Internationalization Data Structures for SOAP Messages of this specification.

/i18np:i18n/@wsp:Optional?

This attribute indicates the optionality for the support of this assertion.

/i18np:i18n/@{any}

This is an extensibility mechanism to allow additional attributes to be added to the element.

The meaning of this assertion, when present in a policy alternative, is that the requester or provider requires the processing of web services internationalization information, as described in 3 Internationalization Data Structures for SOAP Messages of this document.

The wsp:Optional attribute, as a syntactic shortcut, can be used with the i18np:i18np assertion. This indicates two policy alternatives, one which contains the policy assertion, and another which does not. The i18np:i18n element information item MUST NOT include the wsp:Ignorable attribute in its attributes property with a value of true.

The differentiation between describing the support for this capability and the requirement is demonstrated below, using the wsp:Optional attribute.

(01) <wsp:Policy> 
(02)     <i18np:i18n wsp:Optional="true"/>
(03) </wsp:Policy>

(01) <wsp:Policy>
(02)    <i18np:i18n/>
(03) </wsp:Policy>

4.2 Assertion Attachment

Because the i18np:i18n assertion indicates behavior over all messages in a binding, the assertion has an endpoint policy subject. [WS Policy Attachment].

[WS Policy Attachment] defines three [WSDL 2.0] policy attachment points with endpoint policy subject:

• wsdl:interface

• wsdl:binding

• wsdl:endpoint

WS-PolicyAttachment also defines three [WSDL 1.1] policy attachment points with endpoint policy subject:

• wsdl:portType

• wsdl:binding

• wsdl:port

A policy expression containing the i18np:i18n policy assertion MUST NOT be attached to a wsdl:interface or wsdl11:portType; the i18np:i18n policy assertion specifies a concrete behavior whereas the wsdl:interface or wsdl11:portType is an abstract construct.

A policy expression containing the i18np:i18n policy assertion MUST, if present be attached to either a wsdl:binding or wsdl11:binding, or wsdl:endpoint or wsdl11:port.

When attached to either a wsdl:binding or wsdl11:binding, or wsdl:endpoint or wsdl11:port representing a SOAP 1.2 binding, the assertion indicates that the designated endpoint is capable of processing the functionalities described in 3 Internationalization Data Structures for SOAP Messages of this specification.

The following example demonstrates the use of the i18np:i18n policy assertion in [WSDL 2.0].

1 <wsdl:description
2         targetNamespace="http://tns.example.com/"
3         xmlns:tns="http://tns.example.com/"
4         xmlns:wsdl="http://www.w3.org/ns/wsdl"
5         xmlns:wsp="http://www.w3.org/ns/ws-policy"
6         xmlns:i18np="http://www.w3.org/2008/04/ws-i18np">
7         <wsp:Policy xml:id="MyPolicy" >
8                 <i18np:i18n/>
9                <!-- omitted assertions --> 
10        </wsp:Policy>

11        <!-- omitted elements -->

12        <wsdl:binding name="MyBinding" type="tns:MyInterface" >
13                <wsp:PolicyReference
14                        URI="#MyPolicy"
15                        wsdl:required="true" />
16                <!-- omitted elements -->
17        </wsdl:binding>
18 </wsdl:description>

Lines (7-10) are a policy expression that includes an i18np:i18n policy assertion (Line 8) to indicate that the functionality defined in 3 Internationalization Data Structures for SOAP Messages of this document may be used.

Lines (12-17) are a [WSDL 2.0] binding. Lines (13-14) indicate that the policy in Lines (7-10) applies to this binding, specifically indicating that the i18n:international element information item must be accepted over all the messages in the binding. Line (15) indicates that this policy is a required extension.

1 <wsdl:definitions 
2         targetNamespace="example.com"
3         xmlns:tns="example.com"
4         xmlns:wsdl11="http://schemas.xmlsoap.org/wsdl/"
5         xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
6         xmlns:i18np="http://www.w3.org/2008/04/ws-i18np">
  
7         <wsp:Policy xml:id="MyPolicy" >
8                 <i18np:i18n/>
9                <!-- omitted assertions --> 
10        </wsp:Policy>
 
11        <!-- omitted elements -->
 
12        <wsdl:binding name="MyBinding" type="tns:MyPortType" >
13                <wsp:PolicyReference
14                        URI="#MyPolicy"
15                        wsdl11:required="true" />
16                <!-- omitted elements -->
17        </wsdl:binding>

18 </wsdl:definitions>

Lines (7-10) are a policy expression that includes an i18np:i18n policy assertion (Line 8) to indicate that the functionality defined in 3 Internationalization Data Structures for SOAP Messages of this document may be used.

Lines (12-17) are a [WSDL 1.1] binding. Lines (13-14) indicate that the policy in Lines (7-10) applies to this binding, specifically indicating that the i18n:international element information item must be accepted over all the messages in the binding. Line (15) indicates that this policy is a required extension.