User Agent and Assistive Technology Support Notes

Description

The objective of this technique is to use the combination of HTML
Lang attribute, CultureInfo and Language to
correctly specify the language of the entirety of Silverlight content,
or of parts within the Silverlight content.

In general, Silverlight does not attempt to repurpose HTML Lang, because
Silverlight is not HTML. Instead, internally within the Silverlight
content area, Silverlight uses language definition concepts that relate
to XML (Language is a remapping of xml:lang) or .NET
Framework programming (CultureInfo). For these reasons,
HTML Lang techniques as described in [H58]
are not useful for Silverlight programming of Silverlight-specific "parts".

What becomes important in Silverlight application programming then
is to make sure that the HTML language concept of Lang and the Silverlight
language concept of CultureInfo or Lang are not at odds with one another,
or reporting misinformation. In particular, application authors should
avoid situations where an assistive technology has HTML Lang available
for programmatic determination of either page or part, but the effective
runtime language in the Silverlight part is different. The result here
might be that a screen reader that changes functionality such as phonetic
pronunciations would not correctly read the text content from the Silverlight
content. Avoiding this situation is largely a matter of due diligence
on the part of a Silverlight application author, OR on the part of
the Web page author who authors surrounding HTML, in cases where a
Web page is embedding Silverlight content or packages that the Web
page's author did not actively develop and is only consuming/embedding.

The following is a general recommendation that summarizes the detailed
discussion in subsequent subheadings:

If the Silverlight application does not have a strong emphasis
on presenting textual information with a particular language association,
HTML Lang should be left blank. This causes assistive technologies
to defer to either user agent or platform language settings. Silverlight
is able to determine these same language values at run time, and
language behavior of assistive technologies and of Silverlight is
kept synchronized through the use of the same external information
set.

If the Silverlight application DOES have a strong emphasis on
presenting textual information with A SINGLE particular language
association, HTML Lang should be assigned to report that specific
language either for whole page or at least for the Silverlight object
tag. This enables assistive technologies to pick up the value, per H57:
Using language attributes on the html element HTML. Aside from
due diligence during development and deployment, Silverlight application
code might choose to enforce that its runtime CultureInfo is really
the same. This could be addressed with a specific HTML DOM helper
function.

If the Silverlight application has MULTIPLE language associations,
the best option is to separate the Silverlight application into object
parts at the HTML level, to assure that HTML Lang and intended runtime
language do not clash. This is particularly important if the application
is actively resetting CurrentCulture away from the user settings
of platform or user agent. For more information, see SL4: Declaring Discrete Silverlight Objects to Specify Language Parts
in the HTML DOM.

HTML Lang

When Silverlight is embedded in an HTML document with the <object> element,
the value of the HTML Lang attribute of the surrounding HTML becomes
a factor. Browsers process the outer HTML, and the browser's processing
has possible influence over values reported to any DOM script that
acts, or to any accessibility framework that is reporting the browser
content. The preferred way for a Silverlight application to address SC
3.1.1 is to correctly specify the HTML Lang value in the hosting
HTML page. This technique should be used in conjunction with H57:
Using language attributes on the html element HTML. By using the
same language values with both techniques as a better practice, H57
will satisfy 3.1.1 while setting the language value of the Silverlight
content to match will assist authors in meeting SC 3.1.2.

The Silverlight runtime itself does not attempt to inherit language
settings that come from markup that is outside the Silverlight-specific
content. In particular, the HTML Lang attribute applied to the html
tag, Lang on host object tag, specific parameters of the Silverlight
object tag, all have no affect on the value of any Silverlight Language attribute.
Instead, the Silverlight Language defaults to the CultureInfo of
the Silverlight runtime as instantiated by HTML object tag invocation.
It is expected that if a Silverlight application contains extensive
text where language of text is a factor for assistive technology purposes,
developers will manually set the HTML Lang tag to match the Language value
on the Silverlight root element in XAML. Development tools might or
might not enforce or inform the relationship between HTML Lang and
Silverlight Language; that consideration is outside
the scope of Silverlight as a technology. If language is not a major
factor in the application, application authors should consider leaving
HTML Lang blank on the hosting HTML page.

You can programatically determine the value of HTML Lang of surrounding
HTML from within the Silverlight API, by using the DOM-bridging method HtmlElement.GetAttribute.
Otherwise, this can be determined by techniques other than Silverlight's
(such as scripting to the HTML DOM of the hosting browser).

Silverlight Language property

Language is an attribute that is available on all
Silverlight objects that directly represent a UI element. Language
can be queried (or set) by Silverlight managed code run time, such
that the Language value can be programatically determined
within the Silverlight programming model.

Language has a behavior that parallels the behavior
of xml:lang in an XML document: if Language is set on
a parent element, all child elements inherit that Language value.
An actual xml:lang attribute in XAML is also valid for this purpose.

Language can be set at the root of a XAML document,
so that the entire UI shares the same language setting. If Language is
not explicitly set at the root by application markup, Language is
inferred per running instance, based on processing the acting CultureInfo at
run time.

However, another usage is for application authors to set Language on
a specific child element, to override the root-level or client-environment-inferred Language value.
This enables consciously embedding a content part that is deliberately
in a different language than the remainder of the Silverlight content.

Exactly what happens when a Language is set on a
part is not always specified, and is largely a matter of implementation
detail of the individual Silverlight classes that might be a "part".
However, as an informative generalization, the value of Language might
affect considerations such as: how white space is processed (in particular
CR or LF); character sets for fonts; string formatting when using APIs
specifically on that part.

CultureInfo

CultureInfo is a concept that is relevant to .NET
Framework programming. This concept applies to Silverlight because
Silverlight uses a specific implementation of a CLR runtime that uses
.NET Framework principles. CultureInfo potentially
specifies both a language and a culture. This distinction becomes relevant
for advanced string formatting concepts that are provided in the .NET
Framework, such as decimal separators, dates, and currency. For example,
an application author might simply specify "en" if the author
did not care about string formatting, but might specify "en-GB" if
the application was using string formatting for currency values with
the intention of displaying Pounds Sterling as currency unit in string
formatting.

Silverlight applications often run using an inferred CultureInfo based
on the operating system where the user agent browser host exists (in
other words, the culture of the client computer where the Silverlight
application is run). This CultureInfo can be queried
by applications at run time; see CultureInfo.CurrentCulture.
Application authors can deliberately constrain the set of CultureInfo cases
that a Silverlight application can be run under, in order to verify
that necessary string resources for that culture are available in that
application. This is done by setting <SupportedCultures> in the
Silverlight project settings. If a user accesses the application on
a client that is outside the SupportedCultures, the application author
has the following choices:

Use a fallback resource set representing a neutral culture; this
is enabled automatically by the Silverlight resources lookup behavior,
so long as the project includes resources identified as being culture-neutral.
This is the preferred approach.

Use client logic to detect the culture, and initiate a client-side
redirect to request either a different XAP or a different hosting
HTML page.

Trap requests at the server level by checking lang request in
the header. This varies between server implementations, is not a
Silverlight-specific technique, and is not discussed here.

CultureInfo generally applies to the Silverlight
application as a whole. There are advanced techniques whereby worker
threads can be run as separate cultures, but that is not discussed
here and is not relevant because only the main UI thread has relevance
to Web content accessibility. So, if an application author wants to
declare specific language settings for a part (component, region or
control) of the Silverlight application, a different Silverlight-specific
property Language is used.

Examples

These examples show Silverlight behaviors that are based on interpreting
the Language property value, as a way of illustrating
the programmatic determination of language values specifically in the
Silverlight application framework. To determine HTML Lang, application
authors should use the HTML DOM as enabled by browser host scripting,
rather than Silverlight APIs. HTML DOM techniques are not shown here
because they are specific to browsers or scripting frameworks, not
to Silverlight.

Example 1: Language set at root-level of Silverlight content, inherits

This example features a XAML UI and logic that reports information
to demonstrate that the information is programmatically determinable.
This example shows determination of the Language property.

Example 2: Determine CurrentCulture; runtime verification that CurrentCulture and the surrounding HTML's current Lang value do not report different language settings

The following is an event handler that can be hooked to an object
lifetime event such as UserControl.Loaded on the Silverlight
XAML root. This example demonstrates property access to several of
the relevant language properties that are present in Silverlight and
shows a specific way to compare CultureInfo and Lang by a "not
equals" check after constructing a CultureInfo based on the Lang
string. To apply this test, the hosting HTML page may need to be altered
to declare a specific HTML Lang; default Silverlight aspx or html test
pages do not declare HTML Lang.

Resources

Tests

Procedure

Using a browser that supports Silverlight, open an HTML page that
references a Silverlight application through an object tag.

Verify that language settings are respected by individual Silverlight
control characteristics. (Exactly what behavior manifests the language
difference varies per Silverlight class implementation. For some
testing ideas, see Creating
Globally Aware Applications).

Verify that any interaction between HTML Lang in the HTML and
the Language or CultureInfo from the Silverlight application do not
result in a clash of language information, either in terms of basic
application behavior or in how an assistive technology decides to
process language information.

Expected Results

#2 and #3 are true.

If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.