W3C

Web Services Internationalization (WS-I18N)

W3C Working Group Note 22 May 2012

This version:
http://www.w3.org/TR/2012/NOTE-ws-i18n-20120522/
Latest version:
http://www.w3.org/TR/ws-i18n/
Previous version:
http://www.w3.org/TR/2008/WD-ws-i18n-20080415/
Editors:
Addison Phillips, Yahoo!, Inc.
Mary Trumble (until September 2005), IBM
Felix Sasaki, W3C

Abstract

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.

Status of this Document

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.

Note: The working group reached consensus to stop work on this specification. It is being published as a Working Group Note for archival reasons and is no longer being progressed along the W3C's Recommendation Track. The only changes to this document since the last Working Draft is the addition of the note just above, and a correction to the links pointing to what was known as the Olson timezone database, which is now hosted by IANA.

This document was produced by members of the Internationalization Core Working Group, part of the W3C Internationalization Activity.

Comments should be sent to www-international@w3.org. Use "Comment on WS-I18N" in the subject line of your email. The archives for this list are publicly available.

Publication as a Working Group Note 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. 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.

Table of Contents

1 Introduction
1.1 Internationalization Patterns
1.2 Requirements
2 Notation and Terminology
2.1 Notation and Terminology
2.2 Notational Conventions
2.3 Extensibility
2.4 Namespaces
2.5 Requirements on Implementations
3 Internationalization Data Structures for SOAP Messages
3.1 Internationalization Information in SOAP
3.2 Providing Locale Information
3.3 Providing Time zone Information
3.4 Providing Locale Preferences
4 Indicating Use of WS-I18N
4.1 Assertion Syntax
4.2 Assertion Attachment
5 Conformance

Appendices

A Normative References
B XML Schema Documents
C Informative References (Non-Normative)
D Revision Log (Non-Normative)
E Acknowledgements (Non-Normative)


1 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 [RFC 3282] 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 3 Internationalization Data Structures for SOAP Messages is:

In addition, this specification defines a policy assertion (see 4 Indicating Use of WS-I18N.) relying on [WS Policy Framework] to describe the capabilities of these functionalities for a provider or requester, and how to attach a policy with this assertion, relying on [WS Policy Attachment].

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 Notation and Terminology

This section is normative.

This section specifies the terminology used throughout.

2.2 Notational Conventions

This specification uses the following syntax within normative outlines:

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

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.

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.

Note:

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 [I18NScenarios].

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.

SystemLocale
UNIXC/POSIX
JavaLocale("","")
.NETInvariant Culture

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

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:

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.

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

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>

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.

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

(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 Indicating Use of WS-I18N

This section is normative.

This section describes a domain-specific policy assertion for describing the capabilities defined in 3.1 Internationalization Information in SOAP 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 [WS Policy Framework] and Web Services Policy - Attachment [WS Policy Attachment] specifications.

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

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.

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

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.

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.

5 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 2.4 Namespaces) 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 [XML Schema 1], [XML Schema 2] descriptions.

A Normative References

BCP 47
Addison Phillips, Mark Davis, editors. Tags for the Identification of Languages, September 2006. Available at http://www.rfc-editor.org/rfc/bcp/bcp47.txt.
LDML
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/.
OLSON ID
The Time Zone Database defines time zone identifiers and associated zone information. For registration information, see BCP 175 or the IANA time zone database page.
RFC 822
David H. Crocker. Standard for the Format of Arpa Internet Text Messages. Available at http://www.ietf.org/rfc/rfc822.txt. (See http://www.ietf.org/rfc/rfc822.txt.)
RFC 2119
S. Bradner. Key Words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119. Available at http://www.ietf.org/rfc/rfc2119.txt. (See http://www.ietf.org/rfc/rfc2119.txt.)
SOAP 1.2
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/ .
WSDL 1.1
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 .
WSDL 2.0
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/ .
WS Policy Framework
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/ .
WS Policy Attachment
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/ .
XML Infoset
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/ .
XML Schema 1
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/ .
XML Schema 2
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/ .
XPath 1.0
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/ .

B XML Schema Documents

This section is normative.

This section provides the following schemas:

C Informative References (Non-Normative)

CLDR
Common Locale Data Repository, Unicode Consortium. Available at http://www.unicode.org/cldr/.
I18NScenarios
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/. (See http://www.w3.org/International/ws/ws-i18n-scenarios-edit/Overview.xml.)
RFC 3282
Harald Alvestrand. Content Language Headers. IETF Standards track document, May 2002. Work in progress. See http://www.ietf.org/rfc/rfc3282.txt. (See http://www.apps.ietf.org/rfc/rfc3282.html.)

D Revision Log (Non-Normative)

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

E Acknowledgements (Non-Normative)

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