2.1 Overview
This section contains a "framework" or outline for understanding
international issues in Web services.
The framework is based on the Web Services Architecture document [WSA],
which defines a service as follows:
"A service is a set of actions that form a coherent whole from the point of view
of service providers and service requesters. A requester entity is a legal entity
that wishes to make use of a provider entity's Web service. It will use a requester
agent to exchange messages with the provider entity's provider agent. The provider
agent has one ore more services available to it, that it can invoke in behalf of
the requester agent."
The mechanics of the message exchange are (partially) documented
in a Web service description (WSD).
The sequence of events in this framework are as follows:
The requester agent locates a suitable provider agent. This can be accomplished
through UDDI, but also can be accomplished through other means. For example, the
URL of the provider agent may simply have been found in an advertisement somewhere.
The provider agent makes available a Web Services Description (WSD) document.
Using the information in the WSD, the requester agent can formulate a service request.
This will be a SOAP message which is then sent to the provider agent to be acted upon.
The provider agent after receiving the request will invoke the service and
get a response. The response can be the results of the service or an indication
that a fault occurred. Note that the interaction between the provider agent
and the service are independent of the Web Services framework and the design
is left completely to the implementors. The primary requirement is that the
provider agent in turn be able to formulate a response to return to the
requester agent. This response must satisfy both the requirements and
specifications of the Web Services Architecture and the description of the WSD.
If the service request was successfully executed, the provider agent will
formulate a response message and send it to the requester agent.
If the service request was erroneous, or the service could not be
completed for some reason, a fault message will be sent to the requester agent.
The internationalization issues in Web services and as illustrated in the
framework fall into several categories which are common to all Web Services,
regardless of the message exchange pattern used for a specific service.
In the section that follows it is assumed that the service, provider and
requester agents, and data structures (semantics) follow best practices in
internationalization and data structuring. Implicit in these descriptions is
the expectation that data structures use XML Schema types to create locale-neutral
data structures.
Some services may be implemented that do not follow these strictures for reasons
having to do with legacy system implementation or other restriction. These cases
are dealt with in usage scenarios later in this document.
2.2 Natural Language and International Preferences
"Natural Language" refers to human use of language. Generally systems that are
internationalized can produce messages in a variety of different natural languages.
These systems are referred to as "localized", because their messages (and frequently
behavior) are tailored to the individual cultural expectations for a specific target
market or group of individuals.
International preferences are similar to "Natural Language" identification.
Some of the other preferences that a service might be interested in include:
Some of these preferences may be inferred from the natural language by converting
the natural language preference to the service host's "locale" (Note that the provider
agent and service host are not always the same physical host). Other items (such as
timezone) are orthogonal or (like collation) imperfectly or incompletely described
by a natural language identifier. Separating these values requires forethought in
the design of the service and the setting of reasonable default values.
In the sections that follow, you will see the word "locale" used as an adjunct to
natural language. A locale is not a language and the language tags discussed in the
succeeding sections should not be confused with actually being locale tags or
identifiers. However, there is commonly a close relationship between the language
identified by such a tag and the corresponding locale in the underlying platform
and a software process may choose to use language tags to select many of these
additional operational settings or international preferences.
Distributed processing, as with Web services, must allow for several patterns of
behavior in the back end implementation represented by the service.
There are three patterns that such a service may follow. These are:
Language/Locale Neutral
Service Determined
Client Influenced
In each of these patterns, the Web service description (commonly WSDL) and actual
protocol or invocation (SOAP is used in our examples) should reflect the requirements
of the service's own pattern of behavior.
2.2.1 WSDL
Web service descriptions should consider how to communicate language or
locale-of-operation choices in a consistent manner. In the sections that
follow, specific patterns are recommended as good canonical references.
However experience shows that a specific implementation may require additional
contextual information not conveyed with a simple language tag. Generally
this type of additional information should be encoded into the data structure
defined for actual interchange in the message body (such as a soap:body block),
rather than as additional header information as shown in some of the examples below.
This is because specific implementation decisions should be expressed as part of
the service's signature: you may require additional or different data in future versions.
In the examples below, adoption of a generic method for exchanging
"international contextual information" will allow implementations to
better model the natural language and locale processing choices offered
by the services.
In all cases, the implementer should consider adding a language tag to any
operation fault elements to show what language to expect fault messages
to be generated in.
In all cases, descriptive text should be tagged with its actual content language
using the xml:lang attribute (where permitted). Consideration should be given to
providing documentation within services in alternate languages when the service
is expected to be utilized by users such as those in other countries or who speak
other languages.
2.2.2 SOAP
In general, SOAP documents should structure data elements in ways that make the
most sense for the specific underlying implementation. In the examples given,
the user's natural language is passed in an optional header element separate
from the specific data structures required to operate the underlying service logic.
This is by design.
Software developers generally get their language resources (translated messages
and other locale-specific data) from their programming environment. This functionality
is implemented in many ways, but the pattern for writing the logic is always similar:
the language and locale preferences are not included in the parameter list of the
service itself because the processing environment (JVM, OS, .NET framework, etc.)
maintains this information. SOAP Processor implementations should be designed to
recognize natural language information passed in the transport (such as HTTP
Accept-Language) or in SOAP headers as defined in this document or in the
specific implementation-dependent extension of this model and populate or set
the appropriate values in the service's environment.
For example, a .NET SOAP Processor might set the service's thread default
CultureInfo using the language tag. A J2EE implementation might populate
the ServletRequest Locale property with a java.util.Locale constructed from
the ISO639 and ISO3166 fields embedded in a language tag. And so forth.
2.2.3 Faults and Errors
Fault message "text" elements must be labelled with an appropriate language
identifier, as defined in XML 1.0. That is, an xml:lang tag containing an RFC3066
(or its successor) language identifier. If the transport provides the user's
language preference (such as HTTP Accept-Language), then that language or set
of languages should be preferred, followed by the SOAP Processor machine's
local language preference.
Ideally there should always be a "message of last resort" included in the fault.
In many cases this message may be in English, but consideration should be given
to the likely users of the system, including the administrators trying to puzzle
out the error. Numeric (or ASCII-only alpha-numeric) error codes should be
considered for inclusion in all fault messages. This may provide valuable
reference when the text of the message itself is in a language not understood
by the recipient.
When designing specifications intended for interoperability between vendors
or implementations, consideration should be given to enumerating the possible
faults in advance so that reference numbers can be universally and consistently
referenced by disparate implementations.
2.3 Language and Context Negotiation Patterns
As noted above, there are three general patterns or policies that may
be applied to any specific Web service. These three are:
Language Neutral
Service Determined
Client Influenced
2.3.1 Language Neutral
A language neutral service generally is one that executes in the same
way regardless of the current runtime locale or user preferences regarding
language. This implies that all or most strings embedded in the service
are not human readable. This is, by far, the most common pattern. In a
language or locale neutral service, external factors do not alter the
way the service performs. An example of this would be a service that
adds two integers together: 2+2 = 4 in most every locale.
2.3.1.1 Example: GetTimeService returns the current time
GetTimeService can be written as a locale-neutral service. Time of day, although
it is presented with different formats around the world, is measured the
same way everywhere and a standardized single frame of reference is available
to be used. So a service request could return with a response that included
the current UTC (Coordinated Universal Time) time in ISO 8601 format: hh:mm:ss.sss,
i.e. as an XML Schema Part 2: Datatypes [XMLS-2]
time type.
Any application (i.e. a consumer) that triggers an event causing the GetTimeService
request to be sent to a Service Provider, can transform the result into a local or
other time format, including perhaps shifting the time into the local time zone.
With this proposed implementation, from the requester agent to the service provider,
the service and back to the requester agent, the request document and its service
implementation are entirely independent of the locale of the client, the host,
and the implementer. Hence the name locale-neutral.
Of course, the request could also be implemented with dependencies on locale of
the client or the host and this would complicate implementation and increase the
probability of errors in making requests, deploying the service, or implementing
the service.
2.3.1.2 Usage Pattern
Language neutral services, being the default, do not generally announce
themselves in their service contracts, although (other scenarios apply here).
2.3.1.3 WSDL
The Web services description does not require any extra information in order
to perform its operations or communicate its capabilities. Therefore no
additional fields beyond those required by the actual service implementation
should be defined in any of the bindings or operations.
The implementer should consider adding a language tag to any operation
fault elements to show what language to expect fault messages to be generated in.
2.3.1.4 SOAP
No additional attributes or information is required for this pattern.
2.3.1.5 Faults
Fault messages may be generated in a variety of languages simultaneously.
If the transport provides a way of determining the requester agent's preferred
language (such as the Accept-Language header in HTTP), then these preferences
should be used first. In all cases, a "message of last resort" should be generated,
which generally should be in the language and locale of the provider agent or the
language most preferred by the administrator of that system (since that is who will
have to debug any service requests against the system). Many systems are run in
default locales, which often default to the English language. This should be a
consideration in configuring the system.
2.3.2 Service Determined
In the Service Determined pattern, the implementation or configuration
of the service itself or the provider agent determine some aspects of
the processing performed by the service. Generally this can be thought
of as a design-time or deployment-time decision, rather than a runtime
aspect of the service. That is, the service can be relied on to perform
its work in a consistent manner using a predetermined language or locale setting.
2.3.2.1 Example
A service provider is in 3 country markets: U.S., Japan, and Germany.
Each market is supported by a local warehouse.
One of the services that is provided indicates availability of parts.
For a given part number, the following information is returned:
part number, quantity, language, description, size, list price.
If all of the information was maintained in a single database one might see entries like:
| location | part number | quantity | language | description | size | currency | value |
|---|
| U.S. | 123 | 51 | en-US | 6 pack budweiser | 12oz. | USD | 5.99 |
| Japan | 888 | 10 | en-US | 6 pack kirin | 591ml | JPY | 999 |
| Germany | 500 | 20 | en-US | 6 pack Beck's | 300ml | EUR | 8.00 |
@@@@add some native Japanese and german language entries.
However, this company has not yet implemented a worldwide
inventory application and instead each warehouse maintains its
inventory in a separate and independent database and uses
different applications to manage inventory. In fact, the Japanese
warehouse is the only one that uses a system that supports the
Japanese language. Because of its support for Japanese and its
use of legacy encodings instead of Unicode, the Japanese system
cannot properly support German text.
The service provider has implemented a service, GetProductInventory.
The input (inbound message) takes a part number
or part ID. The output (outbound message) returns the following
information: part no., quantity, language, description, size,
list price.
An implementation decision might be taken to provide separate Web services for each warehouse.
Customers on each continent will be directed to a
particular web service that returns the information from the
appropriate warehouse. This pattern is service-determined as it reflects the
inherent nature of the service in each part of the world. (That
is the German warehouse supports clients in Germany.)
This example also demonstrates the "service determined" type of limitation:
it's capabilities are limited by its use of legacy
applications. If the databases were consolidated and suitable
shipping facilities were made available, the service could still
not offer product from any warehouse to any client. The Japanese
clients using the Japanese service provider would not be able to
see all of the potential German beer names. (They could only see them if the names
were transliterated to Japanese or a subset of the Japanese legacy encoding, such as 7-bit ASCII.)
There are several sub-patterns for this.
2.3.2.2 Implementation or Deployment Decision
The service may be written to assume a specific locale or language setting
or the server which hosts the service or provider agent may be statically
configured to use a specific locale. This is generally a poor choice, since
it implies a non-internationalized implementation to start with. However,
legacy code or other choices may require this pattern and not be in the
control of the Web service.
2.3.2.3 Enumerated Set
The service may be enabled for or capable of internationalized operation,
but it may be configured to process all requests in just a few (or, more
likely, just one) language or locale. This allows the service to be deployed
to many locales or for it to serve several markets simultaneously, depending
on how the service and/or its provider agent is configured.
2.3.2.4 Service Determined
Service determined language or locale matching is a pattern that is useful
when the service's performance is explicitly linked to what it does.
For example, a service that returns whether the New York Stock Exchange
will be open or closed on a particular day is strongly linked to the
holiday schedule in the USA. The service may be written in such a way
that it can also be used by other exchanges in other countries, but
the specific service might be written simply to support the needs of this one use.
2.3.2.5 Usage Pattern
Similar to that of Language Neutral, except that the server's local
language preference is expected to affect processing. In most cases the
difference between Language Neutral and Service Defined is that the latter
returns values that have elements consisting of natural language text or are
otherwise locale affected, whereas a Language Neutral service returns values
that can be formatted entirely by the requester agent or requester.
2.3.2.6 WSDL
The Web services description may provide an optional header field in the
operation output element defining the natural language used by the service
at execution time. Since this value is at least partially machine dependent,
the value probably should not be set in the actual service description.
Instead the soap:header or equivalent field should merely be defined as
being available. If the service uses an enumerated set of languages,
it might be wise to ensure that the actual language used is always
passed back in any output.
2.3.2.7 SOAP
This Web service pattern is generally similar to that of Language Neutral.
Processes that are language or locale affected may retrieve their settings
from the default machine settings and the SOAP Processor generally need not
provide any special functionality to activate or achieve this.
2.3.2.8 Faults
Faults are generated as with Language Neutral, except that the service
specific language should also be generated after any user specified value,
but before that of the SOAP Processor, assuming that these three are all
different values and that all are available.
2.3.2.9 S-013: Service Determined Language Preference Leads to Fault
2.3.2.9.1 Scenario Definition
Locale affected fault evaluation.
2.3.2.9.2 Description
Service "A" is defined on Provider "A", running in an English locale.
The service requires that the value of string variable "foo" be less than
"zzz".
Requester "A" is running in a French locale and sends a SOAP request
with foo="écrit".
Provider "A" returns a fault, even though in French the string is "less
than" the evaluated value.
2.3.3 Client Influenced
In this pattern, the service will attempt to match its processing to the
language specified by the user. The service should therefore provide a way
for the user's preference to be communicated, regardless of transport, and
the actual value used to perform the processing should be returned in any
response that may be generated.
2.3.3.1 Example
If the service determined example (GetProductInventory) were upgraded
so that data was globally accessible,
then the pattern could be changed to the client-influenced pattern. In this case, the Web service
GetProductInventory, could return information about inventory
from all warehouses or any specific warehouse, but would take advantage of the user's
language and locale preferences to influence how choices are
returned, the ordering of the choices, and even which choices are displayed.
For example, a user that has a Japanese language preference might
see only the inventory counts for the products available in the
Japanese warehouse, with Japanese language description. Although
the locale-influenced web service may return the "best" responses
for a majority of users, it may be wrong for some percentage,
which on the web may be a large number of users. For example,
Japanese-speaking clients in U.S. would be better served
(perhaps) by inventory from the U.S. warehouse.
A more precise web service design would make the selections of
warehouse and description language, currency, etc. explicit.
However, it is not always possible to present the client all of
the information up front for them to make good choices on a form
with many explicit options. So client-influenced patterns are
often used for this purpose.
2.3.3.2 Usage Pattern
In this usage pattern, the service description and actual execution should be
designed to allow the requester agent to pass the most appropriate value for
the specific invocation of the service.
2.3.3.3 WSDL
Both inbound and outbound headers define a attribute bound to type xsd:language and
labelled with an xml:lang element. The inbound header should allow multiple values
to be passed, in case the first preference is not available. The outbound value
should be a single discrete value: that actually used by the service at execution time.
2.3.3.4 SOAP
Inbound and outbound headers optionally take the element defined in the WSDL.
If not present, the SOAP Processor's local language preference is used. Outbound
headers should reflect as accurately as possible the actual value used in performing
the processing. This may vary from that specified by the user according to the rules
in RFC3066 (or its successor). If no match may be obtained, the results will be
implementation defined--the service may generate a fault if processing can go no
further, but most implementations will probably use the current provider agent's default
locale for the value.
2.3.3.5 Faults
Fault messages should be generated with the requester's preferred language(s),
in order by preference, followed by the provider agent's default language.
2.4 Passing or Matching International Preferences
Implementers may also have to define more complex international behavior, beyond that
described by a mere language choice. It is common for these design decisions to be
specific to the particular application or particular market being serviced.
The use of a "locale" or language preference as a short hand for these more complex
requirements should be carefully considered, and possibly discouraged, in favor of
making the specific information required for proper operation explicit in the service contract.
Nonetheless, in some cases the service implementer may wish to use the language or
locale preference of the end user to determine how the service's processing should proceed.
* various examples
* ... etc. @@@needs more work here
2.5 Natural Language Handling in Faults
SOAP Version 1.2 allows to send fault messages with reason texts in
multiple languages. SOAP Version 1.2 Part 0: Primer [SOAP-0]
explains the <Reason> element as follows:
"It must have one or more env:Text sub-elements, each with a unique xml:lang attribute,
which allows applications to make the fault reason available in multiple languages.
(Applications could negotiate the language of the fault text using a mechanism built
using SOAP headers; however this is outside the scope of the SOAP specifications.)"
This mechanism is suitable
for returning faults in an environment in which the number of languages is relatively small
and the range of languages to be returned is known in advance.
Many actual SOAP implementations are localized into many languages simultaneously.
To prevent faults from becoming overly large and difficult to manage, implementations
should really include some strategy that reduces the set of languages to a minimum and
attempts to match the language of the fault as closely as possible to the client that
ends up viewing the message.
Ideal implementations will include mechanisms for "late localization" of the values.
Future versions of SOAP should probably consider allowing additional structured information
in a Fault so that suitably internationalized clients can perform the localization and
formatting themselves.
2.5.1 S-005: Language Matching for Fault Reason Messages
2.5.1.1 Scenario Definition
The service requester needs to select a matching language from the list of
fault reasons returned by the service provider. This scenario illustrates an
issue that implementations have to take into account.
2.5.1.2 Description
The requester may be unable to (validly) match the returned text values to
its current (end user) language.
Example: SOAP fault reason messages in multiple languages
<env:faultReason>
<env:Text xml:lang="en-US">Processing error</env:Text>
<env:text xml:lang="cs">Chyba zpracování</env:Text>
</env:faultReason>
If the requester prefers "en-GB", then neither string will match
directly for the current requester language preference. Although it
is apparent to a human that en-US is a reasonable match for en-GB, automated
processes are not permitted to make the assumption that languages
with common prefixes are mutually understandable. If the requester prefers
"ja", then selecting the best fallback is even more difficult.
Applies to: SOAP, or an extension of SOAP
2.5.2 S-009: Language Preference for One Way Messages
2.5.2.1 Scenario Definition
Service Oriented Architecture Derivative Patterns One Way Message
2.5.2.2 Description
Service "A" is defined to receive a message from Requester "A" and
deliver to Requester "B" via Service "B". An example of this would be
similar to a mail server triggered by a Web service.
Requester "A" calls Service "A".
Service "B" is unable to complete its message transaction and generates
a fault.
Service "B" should return a message in a language that matches Requester "B"'s
language preference (so that the administrator of that system can use it).
In addition, if Requester "A"'s preferences are available to Requester "B"
(that is, Service "A" got the preferences as part of its input or via an
external mechanism such as the transport), then Requester "A"'s language
preference should be included in the SOAP fault reason text.
For example:
Requester "A" has a language preference of "fr-FR"
Requester "B" is running in an environment with a language preference of "de-DE"
Service "B" is running in an environment with a language preference of "en-US"
Example: The result may look like this:
<env:Reason>
<env:Text xml:lang="fr-FR">French error</env:Text>
<env:Text xml:lang="de-DE">Verarbeitungsfehler</env:Text>
<env:Text xml:lang="en-US">Processing error</env:Text>
</env:Reason>>
2.6 Ordering, Grouping, and Collation in Services
Some types of internationally sensitive processing cannot be inferred solely from a
language identifier. Collation (sorting) is such a process. The collation may even
affect the results that one gets from a Web service. For example, if the service
selects "all offers > c", in certain locales you might receive back entries starting
with "ch" (which is treated as a separate letter). Or if the service returns "all items < z",
in certain locales this may not include accented letters such as Å (A-RING).
See S-009 above for a similar example.