本地化特性和注释Localization Attributes and Comments

Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) 本地化注释是 XAML 源代码内的属性,由开发人员提供,用于提供本地化规则和提示。localization comments are properties, inside XAML source code, supplied by developers to provide rules and hints for localization. Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) 本地化注释包含两组信息:可本地化特性和任意形式的本地化注释。localization comments contain two sets of information: localizability attributes and free-form localization comments. 可本地化特性由 WPFWPF 本地化 API 用于指示哪些资源要进行本地化。Localizability attributes are used by the WPFWPF Localization API to indicate which resources are to be localized. 任意形式的注释是应用程序作者希望包含的任何信息。Free-form comments are any information that the application author wants to include.

本地化注释Localization Comments

如果标记应用程序作者对 XAML 中的特定元素(如对文本长度、字体系列或字体大小的约束)有要求,则可以将此信息传递给本地化人员,其中包含 XAML 代码中的注释。If markup application authors have requirements for specific elements in XAML, such as constraints on text length, font family, or font size, they can convey this information to localizers with comments in the XAML code. 下面是用来向源代码中添加注释的过程:The process for adding comments to source code is as follows:

  1. 应用程序开发人员将本地化注释添加到 XAML 源代码中。Application developer adds localization comments to XAML source code.

  2. 在生成过程中,可以在 .proj 文件中指定是将任意形式的本地化注释留在程序集内、去掉部分注释还是去掉所有注释。During the build process, you can specify in the .proj file whether to leave the free-form localization comments in the assembly, strip out part of the comments, or strip out all the comments. 去掉的注释放在一个单独的文件中。The stripped-out comments are placed in a separate file. 可以使用 LocalizationDirectivesToLocFile 标记指定你的选项,例如:You specify your option using a LocalizationDirectivesToLocFile tag, eg:

    <LocalizationDirectivesToLocFile></LocalizationDirectivesToLocFile><LocalizationDirectivesToLocFile> value </LocalizationDirectivesToLocFile>

  3. 可以分配的值包括:The values that can be assigned are:

    • None - 注释和特性都保留在程序集中,不会生成单独的文件。None - Both comments and attributes stay inside the assembly and no separate file is generated.

    • CommentsOnly - 仅从程序集中去掉注释,并将它们放在单独的 LocFile 中。CommentsOnly - Strips only the comments from the assembly and places them in the separate LocFile.

    • All - 从程序集中去掉注释和特性,并将它们两者都放在单独的 LocFile 中。All - Strips both the comments and the attributes from the assembly and places them both in a separate LocFile.

  4. 从 BAML 中提取可本地化的资源时,BAML 本地化 API 会考虑本地化特性。When localizable resources are extracted from BAML, the localizability attributes are respected by the BAML Localization API.

  5. 以后可以将仅包含任意形式的注释的本地化注释文件合并到本地化过程中。Localization comment files, containing only free-form comments, are incorporated into the localization process at a later time.

下面的示例演示如何将本地化注释添加到 XAML 文件。The following example shows how to add localization comments to a XAML file.

<TextBlock x:Id = "text01"

FontFamily = "Microsoft Sans Serif"

FontSize = "12"

Localization.Attributes = "$Content (Unmodifiable Readable Text)

FontFamily (Unmodifiable Readable)"

Localization.Comments = "$Content (Trademark)

FontSize (Trademark font size)" >

Microsoft

</TextBlock>

在上一示例中,Localization.Attributes 部分包含本地化特性,Localization.Comments 部分包含任意形式的注释。In the previous sample the Localization.Attributes section contains the localization attributes and the Localization.Comments section the free-form comments. 下表显示了特性和注释及其对于本地化人员的含义。The following tables show the attributes and comments and their meaning to the localizer.

本地化特性Localization attributes 含义Meaning
$Content(不可修改的可读文本)$Content (Unmodifiable Readable Text) 无法修改 TextBlock 元素的内容。Contents of the TextBlock element cannot be modified. 本地化人员不能更改单词“Microsoft”。Localizers cannot change the word "Microsoft". 内容对本地化人员可见(可读)。The content is visible (Readable) to the localizer. 内容为文本类别。The category of the content is text.
FontFamily(不可修改但可读)FontFamily (Unmodifiable Readable) 无法更改 TextBlock 元素的字体系列属性,但该属性对本地化人员可见。The font family property of the TextBlock element cannot be changed but it is visible to the localizer.
本地化任意形式的注释Localization free-form comments 含义Meaning
$Content(商标)$Content (Trademark) 应用程序作者告知本地化人员 TextBlock 元素中的内容是商标。The application author tells the localizer that the content in the TextBlock element is a trademark.
FontSize(商标字号)FontSize (Trademark font size) 应用程序作者指示字号属性应遵循标准商标大小。The application author indicates that the font size property should follow the standard trademark size.

可本地化特性Localizability Attributes

Localization.Attributes 中的信息包含对的列表:目标值名称和关联的可本地化值。The information in Localization.Attributes contains a list of pairs: the targeted value name and the associated localizability values. 目标名称可以是属性名称或特殊 $Content 名称。The target name can be a property name or the special $Content name. 如果是属性名称,则目标值为属性的值。If it is a property name, the targeted value is the value of the property. 如果是 $Content,则目标值为元素的内容。If it is $Content, the target value is the content of the element.

有三种类型的特性:There are three types of attributes:

  • CategoryCategory. 它指定是否可以从本地化工具修改值。This specifies whether a value should be modifiable from a localizer tool. 请参阅 CategorySee Category.

  • ReadabilityReadability. 它指定本地化工具是否可读取(和显示)值。This specifies whether a localizer tool should read (and display) a value. 请参阅 ReadabilitySee Readability.

  • ModifiabilityModifiability. 它指定本地化工具是否允许修改值。This specifies whether a localizer tool allows a value to be modified. 请参阅 ModifiabilitySee Modifiability.

这些特性可以按照由空格分开的任何顺序进行指定。These attributes can be specified in any order delimited by a space. 如果指定了重复特性,则最后一个特性将替代前面的特性。In case duplicate attributes are specified, the last attribute will override former ones. 例如,Localization.Attributes = "Unmodifiable Modifiable" 会将 Modifiability 设置为 Modifiable,因为最后一个值是 Modifiable。For example, Localization.Attributes = "Unmodifiable Modifiable" sets Modifiability to Modifiable because it is the last value.

Modifiability 和 Readability 的名称已经揭示了自身的含义。Modifiability and Readability are self-explanatory. “Category”特性提供的预定义类别可帮助本地化人员翻译文本。The Category attribute provides predefined categories that help the localizer when translating text. 类别(如 Text、Label 和 Title)为本地化人员提供了有关如何翻译文本的信息。Categories, such as, Text, Label, and Title give the localizer information about how to translate the text. 还有特殊类别:None、Inherit、Ignore 和 NeverLocalize。There are also special categories: None, Inherit, Ignore, and NeverLocalize.

下表显示了这些特殊类别的含义。The following table shows the meaning of the special categories.

类别Category 含义Meaning
NoneNone 没有为目标值定义类别。Targeted value has no defined category.
继承Inherit 目标值从其父级继承其类别。Targeted value inherits its category from its parent.
忽略Ignore 在本地化过程中将忽略目标值。Targeted value is ignored in the localization process. Ignore 仅影响当前值。Ignore affects only the current value. 它不会影响子节点。It will not affect child nodes.
NeverLocalizeNeverLocalize 无法对当前值进行本地化。Current value cannot be localized. 此类别由元素的子级继承。This category is inherited by the children of an element.

本地化注释Localization Comments

Localization.Comments 包含与目标值有关的任意形式的字符串。Localization.Comments contains free-form strings concerning the targeted value. 应用程序开发人员可以添加一些信息,以便为本地化人员提供有关如何翻译应用程序文本的提示。Application developers can add information to give localizers hints about how the applications text should be translated. 注释格式可以是由“()”括起来的任何字符串。The format of the comments can be any string surrounded by "()". 可以使用“\”对字符进行转义。Use '\' to escape characters.

请参阅See also