学习023-01 Localization Basics（本地化基础）

最新推荐文章于 2025-11-23 19:45:40 发布

原创最新推荐文章于 2025-11-23 19:45:40 发布 · 816 阅读

21 ·

CC 4.0 BY-SA版权

文章标签：

#学习 #.net #XAF #Dev #C# #Localization

XAF 24.1 专栏收录该内容

569 篇文章

订阅专栏

Localization Basics（本地化基础）

The XAF allows you to localize your WinForms, ASP.NET Web Forms, and ASP.NET Core Blazor applications. All strings in the UI are read from the Application Model. Some properties in the Application Model are localizable, i.e., they can have different values depending on their language. For instance, generally the Caption property of any Application Model node is localizable. In this topic, you will learn how to use these properties to localize your applications. To see how a WinForms and ASP.NET Web Forms application can be localized, refer to the Localization section in the FeatureCenter demo, which is supplied with XAF. This demo is located in the %PUBLIC%\Documents\DevExpress Demos 24.1\Components\XAF\FeatureCenter.NETFramework.XPO folder by default.
XAF允许您本地化WinForms、ASP.NET Web Forms和ASP.NET Core Blazor应用程序。UI中的所有字符串均从应用模型（Application Model）读取。应用模型中的某些属性是可本地化的，即它们可以根据语言具有不同的值。例如，通常任何应用模型节点的Caption属性都是可本地化的。在本主题中，您将学习如何使用这些属性来本地化应用程序。要了解如何本地化WinForms和ASP.NET Web Forms应用程序，请参考XAF附带的FeatureCenter演示中的“本地化”部分。该演示默认位于%PUBLIC%\Documents\DevExpress Demos 24.1\Components\XAF\FeatureCenter.NETFramework.XPO文件夹中。

UI Elements to be Localized（需本地化的UI元素）

All UI elements related to data presentation and functionalities can be localized: View Item captions, List View column captions, business object captions, Action captions and Action item captions, and so on. For this purpose, the Application Model’s appropriate nodes have the localizable Caption property.
所有与数据展示和功能相关的UI元素都可本地化：视图项标题、列表视图列标题、业务对象标题、动作标题和动作项标题等。为此，应用模型的相应节点具有可本地化的Caption属性。

In addition, UI elements such as messages, exceptions, button captions, form captions, etc., can also be localized. For this purpose, the Application Model has the special Localization node. This node’s child nodes represent groups of the listed elements. Each group item has the Value property that can be localized.
此外，消息、异常、按钮标题、表单标题等UI元素也可本地化。为此，应用模型有一个特殊的Localization节点。该节点的子节点代表上述元素的分组。每个分组项都有可本地化的Value属性。

If you extend the Application Model with new properties, you can specify which properties are to be localized. Refer to the Application Model Structure topic to learn how to do this. You can also localize custom string constants via the Localization node. Refer to the How to: Localize Custom String Constants topic to learn how.
如果您为应用模型扩展了新属性，可以指定哪些属性需要本地化。有关如何操作，请参考“应用模型结构”主题。您还可以通过Localization节点本地化自定义字符串常量。有关方法，请参考“如何：本地化自定义字符串常量”主题。

General Information（基本信息）

To localize the user interface, use the Model Editor. There you will find the Language combo box on the Model Editor Toolbar.
要本地化用户界面，请使用模型编辑器（Model Editor）。在模型编辑器的工具栏上可以找到“语言”组合框。

在这里插入图片描述

By default, the drop-down list contains two options: (Default language) and Languages Manager…. The (Default language) option corresponds to the default language (English), but not to any country/region. To add more language options, select the Languages Manager…. In the invoked dialog, add the desired languages.
默认情况下，下拉列表包含两个选项：（默认语言）和“语言管理器…”。（默认语言）选项对应默认语言（英语），但不对应任何国家/地区。要添加更多语言选项，请选择“语言管理器…”。在弹出的对话框中，添加所需的语言。

在这里插入图片描述

Note
You can use a specific language (such as “fr-FR”), rather than a neutral language (such as “fr”). The specific language is recommended, because formatting options (e.g., currencies) can be different for cultures that speak the same language (e.g., for France, Belgium and Luxembourg). See the Culture-Specific Formatting topic for details.
您可以使用特定语言（如“fr-FR”），而非中性语言（如“fr”）。建议使用特定语言，因为使用相同语言的不同文化（如法国、比利时和卢森堡）可能有不同的格式设置（如货币）。有关详情，请参阅“特定于区域性的格式设置”主题。

Restart the Visual Studio and select the required language using the Language combo-box within the toolbar.
重启Visual Studio，然后使用工具栏中的“语言”组合框选择所需语言。

在这里插入图片描述

You can setup as many languages as you want. All the changes for a particular language are saved to the corresponding Model.DesignedDiffs.Localization.<language code>.xafml or Model<language code>.xafml_ file. These files resemble the Model.DesignedDiffs.xafml and Model.xafml files, which store the changes made in the Application Model in the default language (English). The changes stored in the Model.DesignedDiffs.Localization.<language code>.xafml and Model<language code>.xafml_ files are also superimposed on the previous model layer. To view these changes, right-click one of these files and choose View Code. For information about files with changes and layers of the Application Model, refer to the Application Model Basics topic.
您可以设置任意数量的语言。特定语言的所有更改都保存在相应的Model.DesignedDiffs.Localization.<language code>.xafml或Model<language code>.xafml_文件中。这些文件与Model.DesignedDiffs.xafml和Model.xafml文件类似，后两者存储默认语言（英语）下应用模型中的更改。Model.DesignedDiffs.Localization.<language code>.xafml和Model<language code>.xafml_文件中存储的更改也会叠加到之前的模型层上。要查看这些更改，请右键单击其中一个文件并选择“查看代码”。有关包含更改的文件和应用模型层的信息，请参考“应用模型基础”主题。

Refer to the How to: Localize an XAF Application topics to learn more about the application localization process.
有关应用程序本地化过程的更多信息，请参考“如何：本地化XAF应用程序”主题。

Ways to Specify an Application Language（指定应用程序语言的方式）

In the Application Model（在应用模型中）

To specify the language in which your application will run, invoke the Model Editor, navigate to the Application node and set the required language for the IModelApplication.PreferredLanguage property. The following options are available.
要指定应用程序运行时使用的语言，请调用模型编辑器，导航到Application节点，并为IModelApplication.PreferredLanguage属性设置所需语言。可用选项如下。

(Default language)（默认语言）
None of the generated Model.DesignedDiffs<language code>.xafml_ and Model<language code>.xafml_ files will be considered. All localizable elements will be set to the values specified in the Model.DesignedDiffs.xafml and Model.xafml files.
不会考虑生成的Model.DesignedDiffs<language code>.xafml_和Model<language code>.xafml_文件。所有可本地化元素都将设置为Model.DesignedDiffs.xafml和Model.xafml文件中指定的值。
(User language)（用户语言）
The values from the Model.DesignedDiffs<language code>.xafml_ and Model<language code>.xafml_ files will be superimposed on the values from the files with the default language (Model.DesignedDiffs.xafml and Model.xafml). In Windows Forms applications, the <language code> is taken from the operating system settings. In ASP.NET Web Forms applications, the <language code> is determined by browser preferences. If there are no appropriate Model.DesignedDiffs<language code>.xafml_ and Model<language code>.xafml_ files, only default values will be applied.
Model.DesignedDiffs<language code>.xafml_和Model<language code>.xafml_文件中的值将叠加到默认语言文件（Model.DesignedDiffs.xafml和Model.xafml）的值上。在Windows Forms应用程序中，<language code>取自操作系统设置。在ASP.NET Web Forms应用程序中，<language code>由浏览器偏好设置决定。如果没有相应的Model.DesignedDiffs<language code>.xafml_和Model<language code>.xafml_文件，则仅应用默认值。
Certain Language（特定语言）
The values from the Model.DesignedDiffs<language code>.xafml_ and Model<language code>.xafml_ files, which correspond to the specified language, will be superimposed.
将叠加与指定语言对应的Model.DesignedDiffs<language code>.xafml_和Model<language code>.xafml_文件中的值。

In code（在代码中）

If you need to set the preferred language in dependence to a condition, handle the XafApplication.CustomizeLanguage event. Note that the language you set in this event handler cannot be changed via the Application Model at runtime.
如果需要根据条件设置首选语言，请处理XafApplication.CustomizeLanguage事件。请注意，在此事件处理程序中设置的语言在运行时无法通过应用模型更改。

Localization Rules（本地化规则）

When building a UI, the system uses the appropriate language-specific xafml files. For instance, if German must be used in an application, the system uses the Model_de.xafml xafml file, where properties are set to German values. However, some values might not be found in language-specific xafml files. This may occur if you omitted a property when you were localizing your application to the required language. In this instance, there are two rules with which to get the value.
构建UI时，系统会使用相应的特定语言xafml文件。例如，如果应用程序必须使用德语，系统会使用Model_de.xafml文件，其中的属性设置为德语值。但是，在特定语言的xafml文件中可能找不到某些值。这可能是因为在将应用程序本地化为所需语言时遗漏了某个属性。在这种情况下，有两条规则用于获取值。

If the property, whose localized value is not found, is not calculated from another property, its value is taken from the xafml file in the default language.
如果未找到本地化值的属性不是从其他属性计算得出的，则其值取自默认语言的xafml文件。

在这里插入图片描述

If the property, whose localized value is not found, is calculated from another property, the localized value of the source property is taken. However, if the source property’s localized value is not found, the calculated property’s value is taken from the xafml file in the default language (dotted arrow in the image below).
如果未找到本地化值的属性是从其他属性计算得出的，则采用源属性的本地化值。但是，如果源属性的本地化值也未找到，则计算属性的值取自默认语言的xafml文件（下图中的虚线箭头）。

在这里插入图片描述

The list of supported languages can be retrieved from these sources:
支持的语言列表可从以下来源获取：

1.The Languages key from the configuration file’s appSettings section:
配置文件appSettings部分中的Languages键：

XML 
<configuration>
  <appSettings>
    <!-- ... -->
    <add key="Languages" value="en;de;fr" />
    <!-- ... -->
  </appSettings>
  <!-- ... -->
<configuration>

The value of this key consists of available language codes, separated by a semicolon.
该键的值由可用的语言代码组成，用分号分隔。

2.For ASP.NET Core Blazor UI applications. From appsettings.json. This languages list is used to:
对于ASP.NET Core Blazor UI应用程序，来自appsettings.json。此语言列表用于：

load satellite assemblies
加载附属程序集
specify the RequestLocalizationMiddleware’s RequestLocalizationOptions.SupportedCultures option.
指定RequestLocalizationMiddleware的RequestLocalizationOptions.SupportedCultures选项。

The first language in this list is used as a default language and is specified in the RequestLocalizationOptions.SupportedCultures.
此列表中的第一种语言用作默认语言，并在RequestLocalizationOptions.SupportedCultures中指定。

appsettings.json 
{
    //
    "DevExpress": {
        "ExpressApp": {
            "Languages": "en;de;fr"
             // ...
        }
    }
}

3.From the current project/application differences file names.
来自当前项目/应用程序的差异文件名。

在这里插入图片描述

When the Model Editor is invoked as the Visual Studio designer, only the last source is available. At runtime, these sources are joined. So, if there are no differences for a certain language, but this language is added in the configuration file, then this language can be specified as preferred, and the values stored in the corresponding satellite assembly will be used in the UI.
当模型编辑器作为Visual Studio设计器调用时，仅最后一个来源可用。在运行时，这些来源会合并。因此，如果某语言没有差异文件，但在配置文件中添加了该语言，则可以将该语言指定为首选语言，UI中将使用相应附属程序集中存储的值。

Note
To load localized property values from satellite assemblies, the Visual Studio or running application must be restarted. When the language is added, but satellite assemblies are unavailable, you can get the System.IO.FileNotFoundException exceptions while debugging. These exceptions are properly handled internally, and do not cause the application crash at runtime. To skip these exceptions automatically, click the Debug | Exceptions… item in Visual Studio menu and uncheck Common Language Runtime Exceptions | System.IO.
要从附属程序集中加载本地化的属性值，必须重启Visual Studio或运行中的应用程序。当添加了语言但附属程序集不可用时，调试时可能会出现System.IO.FileNotFoundException异常。这些异常在内部已妥善处理，不会导致应用程序在运行时崩溃。要自动跳过这些异常，请点击Visual Studio菜单中的“调试”|“异常…”，取消勾选“公共语言运行时异常”|“System.IO”。