Web Services Internationalization (WS-I18N)

WS-I18N

&status;

ⅅ&MM;&year; http://www.w3.org/TR/2005/WD-ws-i18n-20050914/ XML http://www.w3.org/TR/ws-i18n Addison Phillips Invited Expert Mary TrumbleIBM

This document (hereafter referred to as "WS-I18N") describes enhancements to SOAP messaging to provide internationalized and localized operation via locale and international preference negotiation. These mechanisms can be used to accommodate a wide variety of development models for international usage.

WS I18N also provides a general-purpose mechanism for associating a "locale policy" with messages. It is designed to be extensible (e.g. support multiple international preferences and locale identifier models).

By using the SOAP extensibility model, SOAP-based specifications are designed to be composed with each other to provide a rich messaging environment. By itself, WS-I18N does not ensure internationalized operation or that localized operation will occur nor does it provide a complete internationalization solution. WS-I18N is a building block that is used in conjunction with other Web service and application-specific protocols, and which can accommodate a wide variety of locale and international support models. Implementing this specification does not by itself enable international functionality in the underlying Web services or providers, but it does provide a framework for globalization that enabled products can leverage, as well as a way for enabled products to interact with systems that are not enabled.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a First Public Working Draft of "Web Services Internationalization (WS-I18N)".

This document describes enhancements to SOAP messaging to provide internationalized and localized operation via locale and international preference negotiation. These mechanisms can be used to accommodate a wide variety of development models for international usage. WS-I18N also provides a general-purpose mechanism for associating a "locale policy" with messages. It is designed to be extensible (e.g. support multiple international preferences and locale identifier models).

This document was developed by the Internationalization Core Working Group, part of the W3C Internationalization Activity. The Working Group expects to advance this Working Draft to Recommendation Status (see W3C document maturity levels).

Send your comments to www-i18n-comments@w3.org. Use "Comment on WS-I18N WD" in the subject line of your email. The archives for this list are publicly available.

Per section 4 of the W3C Patent Policy, Working Group participants have 150 days from the title page date of this document to exclude essential claims from the W3C RF licensing requirements with respect to this document series. Exclusions are with respect to the exclusion reference document, defined by the W3C Patent Policy to be the latest version of a document in this series that is published no later than 90 days after the title page date of this document.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced under the 5 February 2004 W3C Patent Policy. Since the Working Group expects this document to become a W3C Recommendation, under that policy it has associated W3C Royalty-Free Licensing oblications. The Working Group maintains a public list of patent disclosures relevant to this document; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

This is the first version of this document.

Introduction

Web services technology provides application-to-application communication over the Internet. The Web Services Glossary 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 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 () 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.

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.

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.

Notation and Terminology

This section specifies the terminology used throughout.

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 .

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 referenced by this specification is:

http://unicode.org/cldr/

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

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.

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 .

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 .

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

Sub-elements of international<i18n:international S:mustUnderstand="..." S:actor:"..."> ... </i18n:international>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 (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:

Examples of locale values<locale>en-US</locale>  <locale>$default</locale>  <locale>zh-Hant-HK</locale>  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 or an Olson ID from the 'tzinfo' database. Note that RFC 822 zone offsets are not complete time zone identifiers and Olson identifiers should be preferred.

For example:

The tz element<tz>GMT-0300</tz> <tz>America/Los_Angeles</tz>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:

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 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.

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>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:

WSDL Property for operation of a particular service<definitions targetNamespace="http://example.com/example" xmlns:ns1="http://example.com/example"> <interface name="ns1:Thing">  <feature uri="http://www.w3.org/2005/09/ws-i18n" required="true"/> <operation name="someOperation">  <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">  <property uri="http://www.example.com/International/ws/i18n" required="true"> <value>fr-FR</value>  </property> ... </operation> </interface> Examples

Here are some document examples:

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>

References Common Locale Data Repository, Unicode Consortium. Available at http://www.unicode.org/cldr/. Debasish Banerjee, Martin Dürst, Mike McKenna, Addison Phillips, Takao Suzuki, Tex Texin, Andrea Vine. Web Services Internationalization Usage Scenarios. W3C Working Draft December 2003. Available at http://www.w3.org/TR/2004/NOTE-ws-i18n-scenarios-20040730/. The latest version of ws-i18n-scenarios is available at http://www.w3.org/TR/ws-i18n-scenarios/. Mark Davis, Locale Data Markup Language (LDML), Unicode Technical Standard #35. Available at http://unicode.org/reports/tr35/tr35-5.html. The latest version of LDML is available at http://unicode.org/reports/tr35/. David H. Crocker. Standard for the Format of Arpa Internet Text Messages. Available at http://www.ietf.org/rfc/rfc822.txt. S. Bradner. Key Words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119. Available at http://www.ietf.org/rfc/rfc2119.txt. Addison Phillips, Mark Davis. Tags for the Identification of Languages. IETF Internet-Draft, June 2005. Work in progress. See http://www.ietf.org/internet-drafts/draft-ietf-ltru-registry-12.txt Harald Alvestrand. Content Language Headers. IETF Standards track document, May 2002. Work in progress. See http://www.ietf.org/rfc/rfc3282.txt. Time Zone Information Database. Available at http://www.twinsun.com/tz/tz-link.htm. Huga Haas, Allen Brown. Web Services Glossary. W3C Working Group Note 11 February 2004. Available at http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/. The latest version of ws-gloss is available at http://www.w3.org/TR/ws-gloss/. Martin Gudgin, Marc Hadley. Web Services Addressing (WS-Addressing). W3C Candidate Recommendation 17 August 2005. Available at http://www.w3.org/TR/2005/CR-ws-addr-core-20050817/. The latest version of Web Services Addressing is available at http://www.w3.org/TR/ws-addr-core/.