]>
Web Services Internationalization (WS-I18N) WS-I18N &status; ⅅ &MM; &year; http://www.w3.org/TR/2008/WD-ws-i18n-2008@@@@/ XML http://www.w3.org/TR/ws-i18n http://www.w3.org/TR/2008/WD-ws-i18n-20080415/ Addison Phillips Yahoo!, Inc. Mary Trumble (until September 2005) IBM Felix Sasaki W3C

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

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 services 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 a Web services interaction, 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 document (hereafter referred to as "WS-I18N") describes enhancements to SOAP messaging to provide internationalized and localized operations using locale and international preferences. These mechanisms can be used to accommodate a wide variety of development models for international usage.

This is an updated Working Draft of "Web Services Internationalization (WS-I18N)". This document was produced by members of the Internationalization Core Working Group, part of the W3C Internationalization Activity. The Working Group intends to publish this document as a Working Group Note.

The major change in this version of the document is the adoption of and as the means to realize the functionality of Web Services Internationalization. No diff-marked version against the previous version of this document is provided, since this change resulted in a thorough restructuring of the document.

Comments should be sent 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.

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 by a group operating under the 5 February 2004 W3C Patent Policy. The group does not expect this document to become a W3C Recommendation. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; 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) must disclose the information in accordance with section 6 of the W3C Patent Policy.

 en

This is the second publication of this document.
Introduction

This section is informative.

Web services technology provides application-to-application communication over the Internet. Most programming languages and operating environments use an internationalization model that assumes that the user's preferences (generally embodied as a "locale", that is: 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. However, neither Accept-Language nor user identity is appropriate for the internationalization of Web services.

This specification proposes an alternative mechanism to provide locale information in a web services interaction. It 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. The functionality provided by this mechanism defined in is:

identify whether a service is locale-affected;

identify the specific locale used by a provider;

accept the specific locale and language preference(s) of the requester;

optionally identify the specific locale or language preference(s) used by the provider in a response.

In addition, this specification defines a policy assertion (see .) relying on to describe the capabilities of these functionalities for a provider or requester, and how to attach a policy with this assertion, relying on .

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.

 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 :

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.

An internationalization "policy", see , can be used to describe the capability of these functionalities.

 Notation and Terminology

This section is normative.

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 .

 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 . Information item properties are indicated by the style infoset property.

XML namespace prefixes (see ) 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 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 descriptions.

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.

 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.

Prefix Namespace Specification
i18n http://www.w3.org/2005/09/ws-i18n This document,
i18np http://www.w3.org/2008/04/ws-i18np This document,
ldml http://unicode.org/cldr/
S http://www.w3.org/2003/05/soap-envelope
xs http://www.w3.org/2001/XMLSchema or , depending on the context
wsdl http://www.w3.org/ns/wsdl or http://schemas.xmlsoap.org/wsdl/ , depending on context or
wsp http://www.w3.org/ns/ws-policy or , depending on the context
Requirements on Implementations

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

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

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.

Internationalization Data Structures for SOAP Messages

This section is normative.

SOAP documents that need to send international preferences SHOULD include the i18n:international element information item 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.

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:

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

This required element information item defines the locale, see .

This optional element information item defines the timezone, see .

This optional element information item defines the locale preferences, see .

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

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.

In practice, the i18n:international element information item 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 .

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

Locale settings in different systems
System Locale
UNIX C/POSIX
Java Locale("","")
.NET Invariant Culture

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

Examples of locale values (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 --> 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> ( value) | (02) (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 or an 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:

The tz element information item (01) <i18n:tz>GMT-0300</i18n:tz> (02) <i18n:tz>America/Los_Angeles</i18n:tz> 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.

The following sections demonstrate various information which can be conveyd using i18n:preferences.

Providing Language Information

The optional i18n:language element information item MAY appear at most one time in the children property of the i18n:preferences element information item.

(01) <i18n:language> (locale identifier based on [BCP 47]) </i18n:language>

The i18n:language element information item represents the natural language of the web services interaction. Its value MUST be a valid language tag.

An example of the usage of i18n:language is given below.

The i18n:language element information item using

In this example, the i18n:language element information item is used to override the natural language to French (fr). The German locale (de-DE) is used for the rest of the locale sensitive service operations such as data formatting.

(01) <i18n:international> (02) <i18n:locale>de-DE</i18n:locale> (03) <i18n:preferences> (04) <i18n:language>fr</i18n:language> (05) </i18n:preferences> (06) </i18n:international>

An example of the usage of the i18n:collation element information item is given below.

Usage of the i18n:collation element information item

In this example, the i18n:collation element information item is used to convey the usage of the "i;ascii-casemap" collation, which operates on US-ASCII letters in a case-insensitive manner.

(01) <i18n:international> (02) <i18n:locale>en-US</i18n:locale> (03) <i18n:preferences> (04) <i18n:collation>i;ascii-casemap</i18n:collation> (05) </i18n:preferences> (06) </i18n:international> Providing Collation Information

The optional i18n:collation element information item MAY appear at most one time in the children property of the i18n:preferences element information item.

(01) <i18n:collation>(collation identifier based on (02) the IANA Collation Registry</i18n:collation>

The i18n:collation element information item represents the collation used in the web services operation. Its value MUST be a valid collation identifier.

Adding further Extensions

An example of the usage of i18n:preferences for adding further extensions is given below. It describes preferences using .

preferences element information item using

In this example, the i18n:preferences element information item used to convey the usage of a specific metric system.

(01) <i18n:preferences> (02) <ldml:measurementSystem type="metric" /> (03) </i18n:preferences> Indicating Use of WS-I18N

This section is normative.

This section describes a domain-specific policy assertion for describing the capabilities defined in of this document. The mechanism for indicating that a requestor or provider uses the capabilities (or requires their usage) defined in this specification is through the use of the Web Services Policy - Framework and Web Services Policy - Attachment specifications.

This specification defines one policy assertion called i18np:i18n, reading as "Web Services Internationalization Policy". describes the syntax of this assertion, describes its relevant policy subjects and attachment points.

Assertion Syntax

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

The i18np:i18n element information item indicating the use of the mechanisms defined in of this specification.

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

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

Subject supports WS-I18N(01) <wsp:Policy> (02) <i18np:i18n wsp:Optional="true"/> (03) </wsp:Policy> Subject requires WS-I18N(01) <wsp:Policy> (02) <i18np:i18n/> (03) </wsp:Policy> Assertion Attachment

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

defines three policy attachment points with endpoint policy subject:

wsdl:interface

wsdl:binding

wsdl:endpoint

WS-PolicyAttachment also defines three 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 of this specification.

The following example demonstrates the use of the i18np:i18n policy assertion in .

Use of i18np:i18n policy assertion in WSDL 2.0 7 8 9 10 11 12 13 16 17 18 ]]>

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

Lines (12-17) are a 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.

Use of i18np:i18n policy assertion in WSDL 1.1 7 8 9 10 11 12 13 16 17 18 ]]>

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

Lines (12-17) are a 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.

 Conformance

This section is normative.

An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST level requirements defined herein. The XML namespace identifiers for this specification (listed in ) MUST not be used unless they are compliant with this specification.

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

 Normative References Addison Phillips, Mark Davis, editors. Tags for the Identification of Languages, September 2006. Available at http://www.rfc-editor.org/rfc/bcp/bcp47.txt. Mark Davis, editor. Locale Data Markup Language (LDML), Unicode Technical Standard #35. Available at http://unicode.org/reports/tr35/tr35-8.html. The latest version of LDML is available at http://unicode.org/reports/tr35/. The TZID Database (aka Olson timezone database) Timezone and daylight savings information.. Available at ftp://elsie.nci.nih.gov/pub/. For general information, see http://www.twinsun.com/tz/tz-link.htm 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. Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, editors. SOAP Version 1.2 Part 1: Messaging Framework (Second Edition), W3C Recommendation 27 April 2007. Available at http://www.w3.org/TR/2007/REC-soap12-part1-20070427/. The latest version of SOAP 1.2 is available at http://www.w3.org/TR/soap12-part1/ . Erik Christensen, Francisco Curbera, Greg Meredith, Sanjiva Weerawarana, editors. Web Services Description Language (WSDL) 1.1, W3C Note 15 March 2001. Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315. The latest version of WSDL 1.1 is available at http://www.w3.org/TR/wsdl . Roberto Chinnici, Jean-Jacques Moreau, Arthur Ryman, Sanjiva Weerawarana, editors. Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language, W3C Recommendation 26 June 2007. Available at http://www.w3.org/TR/2007/REC-wsdl20-20070626. The latest version of WSDL 2.0 is available at http://www.w3.org/TR/wsdl20 . Asir S Vedamuthu, David Orchard, Frederick Hirsch, Maryann Hondo, Prasad Yendluri, Toufic Boubez, Ümit Yalçinalp, editors. Web Services Policy 1.5 - Framework, W3C Recommendation 04 September 2007. Available at http://www.w3.org/TR/2007/REC-ws-policy-20070904. The latest version of WS Policy is available at http://www.w3.org/TR/ws-policy/ . Asir S Vedamuthu, David Orchard, Frederick Hirsch, Maryann Hondo, Prasad Yendluri, Toufic Boubez, Ümit Yalçinalp, editors. Web Services Policy 1.5 - Attachment, W3C Recommendation 04 September 2007. Available at http://www.w3.org/TR/2007/REC-ws-policy-attach-20070904. The latest version of WS Policy Attachment is available at http://www.w3.org/TR/ws-policy-attach/ . John Cowan, Richard Tobin, editors. XML Information Set (Second Edition), W3C Recommendation 4 February 2004. Available at http://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version of XML Infoset is available at http://www.w3.org/TR/xml-infoset/ . Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, editors. XML Schema Part 1: Structures Second Edition, W3C Recommendation 28 October 2004. Available at http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/. The latest version of XML Schema 1 is available at http://www.w3.org/TR/xmlschema-1/ . Paul V. Biron, Ashok Malhotra. XML Schema Part 2: Datatypes Second Edition, W3C Recommendation 28 October 2004. Available at http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. The latest version of XML Schema 2 is available at http://www.w3.org/TR/xmlschema-2/ . James Clark, Steve DeRose, editors. XML Path Language (XPath), W3C Recommendation 16 November 1999. Available at http://www.w3.org/TR/1999/REC-xpath-19991116. The latest version of XPath 1.0 is available at http://www.w3.org/TR/xpath . XML Schema Documents

This section is normative.

This section provides the following schemas:

XML Schema document for WS-I18N (see of this specification)

XML Schema document indicating the use of WS-I18N (see of this specification)

 Informative References Common Locale Data Repository, Unicode Consortium. Available at http://www.unicode.org/cldr/. C. Newman, M. Duerst, A. Gulbrandsen. Internet Application Protocol Collation Registry. Available at http://www.rfc-editor.org/rfc/rfc4790.txt. 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/. Harald Alvestrand. Content Language Headers. IETF Standards track document, May 2002. Work in progress. See http://www.ietf.org/rfc/rfc3282.txt. Revision Log

The following revision log contains changes since the publication from 15 April 2008.

Created three subsections of .

Added two element declarations to the XML Schema document for WS-I18N: i18n:collation (as part of the i18n:preferences element) and i18n:language (as part of the i18n:international element).

Replaced "_" by "-" in locale identifiers to make it possible to base these on .

The following revision log contains changes since the publication from 14 September 2005.

Kept the functionality of Web Services Internationalization, but realized it now relying on and . This change lead to a complete restructuring of the document.

 Acknowledgements

This document is the work of the W3C i18n Core Working Group.