FrameworkElement.Language Property

Reference

Definition

Namespace:: Windows.UI.Xaml

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Gets or sets localization/globalization language information that applies to a FrameworkElement, and also to all child elements of the current FrameworkElement in the object representation and in UI.

public:
 property Platform::String ^ Language { Platform::String ^ get(); void set(Platform::String ^ value); };

winrt::hstring Language();

void Language(winrt::hstring value);

public string Language { get; set; }

var string = frameworkElement.language;
frameworkElement.language = string;

Public Property Language As String

<frameworkElement Language="languageString" />

Property Value

String

Platform::String

winrt::hstring

A string specifying language and culture that follows the Internet Engineering Task Force (IETF) BCP 47 standards. For example, U.S. English is "en-US".

Remarks

The Language property is intended for setting a per-element language setting on selected elements in a larger UI. The main reason for doing this is to influence text-related properties and settings, such as what the default or fallback FontFamily should be for text presentation.

The default value for this property is the top language from the app language list, which is derived from the user's ranked list of preferred languages. We recommend that you leave the default for this property, as it will provide the best end user experience in terms of font fallback. For example, if the app is displaying East Asian content and the user has specified an East Asian language in their user profile, the content will most reliability show up in the desired East Asian font.

The Language property is mainly relevant for these FrameworkElement subclasses:

The TextElement class also has a Language property, and it has similar purpose and behavior for TextElement subclasses such as Run.

If it's not specifically set as an attribute, the default value for Language is determined by other, larger factors that influence the globalization and localization settings for your app. This includes the user's system settings. For more info, see Globalizing your app.

Setting Language on UI elements is only a small part of what you might do to prepare an app for localization and globalization. For example, you typically need to name or load resources such as strings and images and include these resources in your app package. You also need to apply x:Uid directive values to any elements that should use resource qualifiers to obtain the language-specific resource. For more info, see Globalizing your app.

When you set Language in markup, you should consider using a RESW resources file to specify the BCP 47 string, rather than hard-coding a string in the markup. Specify an x:Uid directive value on that element where you want to specify Language so that the resource system can target the element. Then provide a string resource of the BCP 47 string that matches the resources folder name the resource comes from. You'll probably already have a RESW file in your project that is providing the conventional localized UI strings. For more info, see Quickstart: Translating UI resources.

FrameworkElement.Language and xml:lang

XAML is a language that is based on XML and follows basic XML rules. This includes supporting XML constructs such as the lang attribute from the XML language XML namespace. You can specify xml:lang on an object element for a FrameworkElement subclass, and it is treated the same as if it were a Language value, because it uses the same BCP 47 handling of the string attribute value. You can also specify xml:lang on an object element that is not a FrameworkElement subclass, although that typically won't result in any behavior change on that element.

Language deliberately uses a property inheritance structure so that a value for Language set on the root element will propagate that value to all child objects in the visual tree that are also a FrameworkElement. This parallels the xml:lang behavior in XML and the XML DOM. Also, you can use Language at run time to read an xml:lang value that was set in the markup, so long as the element you're reading from is a FrameworkElement subclass that has a Language property.

However, you can't specify both the Language and xml:lang attributes on the same object element, that will throw a XAML parse error.

Migration notes

This API takes a string. In the equivalent Microsoft Silverlight and Windows Presentation Foundation (WPF) API, the type of this property is a helper object that wraps the same string. You can import XAML from other projects without noticing this difference, because how XAML parses the string is identical.

Applies to

Jaa