本地化应用程序¶

本地化涉及不同资源的创建和使用，例如您要在应用程序中支持的地区的文本、纹理和样式等。

Kanzi 间接使用资源 ID 来使用本地化资源，这些资源 ID 为每个区域设置保存一个单独的值。为了跟踪本地化资源和区域设置，Kanzi 使用本地化表。您可以在 Library > Localization 中的本地化表中查看应用程序使用的所有本地化资源和区域设置。

要本地化您的 Kanzi 应用程序：

将您的工程中要本地化的资源添加到本地化表中。请参阅添加资源至本地化表。
本地化资源。请参阅本地化文本资源和本地化其他资源。
编辑本地化资源。请参阅编辑本地化的资源。

您也可以本地化主题。请参阅本地化主题。

通过完成教程，了解如何本地化您的 Kanzi 应用程序。请参阅教程：本地化您的应用程序。

添加资源至本地化表¶

如果您有一个完整的 Kanzi 应用程序需要本地化，或者您向已经本地化的 Kanzi 应用程序添加了内容，则必须为要本地化的项目创建资源 ID，并将其添加到本地化表中。在为要本地化的资源创建资源 ID 并将其添加到本地化表后，您可以开始本地化您的 Kanzi 应用程序。请参阅本地化文本资源和本地化其他资源。

要创建资源 ID 并将它们添加到本地化表中：

在 Node Tree 中，右键单击 Screen 节点并选择 Add Resources to a Localization Table。

使用 Add Resources to a Localization Table 命令在 Screen 节点上时，Kanzi Studio 使您能够将项目中的所有资源添加到本地化表并对其进行本地化。

要仅为选定节点及其树添加资源到本地化表中，请右键单击该节点并选择 Add Resources to a Localization Table。Kanzi Studio 仅在 Add Resources to a Localization Table 窗口中显示该节点树中使用的资源。
在 Add Resources to a Localization Table 窗口中：
1. 将 Localization Table 设置为您要添加资源的本地化表。如果您还没有本地化表，请选择 <Create New>。
  
  本地化表包含有关哪些地区使用哪些资源的信息。
2. 选择要在 Add Resources to a Localization Table 窗口中显示的资源类型。例如，要仅显示文本和图像资源，请选择和。
3. 在列出了您所选类型的所有资源的表格中，点击要添加到您所选本地化表中的资源旁边的复选框。要更改资源 ID，请双击资源 ID 并输入新名称。
  
  Kanzi Studio 为使用相同 Text 属性值的 Text Block 节点创建单个资源 ID。这些节点在本地化表中共享相同的条目。
4. 单击 Add。
您可以开始本地化您的 Kanzi 应用程序。请参阅本地化文本资源、本地化其他资源和编辑本地化的资源。

本地化文本资源¶

Kanzi 使用 gettext PO 文件格式来处理本地化文本资源，并根据字符串中的第一个字符设置文本方向。

在 PO 文件中，您可以使用 Unicode 字符。使用 Unicode 字符，您还可以控制文本方向，例如在从右到左的区域中控制从左到右文本的方向。要了解如何使用 Unicode 字符控制文本方向，请参阅 How to use Unicode controls for bidi text。

使用 Unicode 字符时，确保正确插入它们。在 Windows 和 Linux 上，您可以使用 Character Map 应用程序。

要了解有关 gettext PO 文件格式的更多信息，请参阅 The Format of PO Files。

如果您想为本地化文本资源定义自己的导入和导出格式，请使用 Kanzi Studio localization plugin API 创建一个 Kanzi Studio 插件。您可以在 <KanziWorkspace>/Examples/CsvPlugin 目录中找到一个此类插件的示例，该插件使用 CSV 将文本导出和导入到本地化表中。

备注

当本地化文本包含简单和复杂脚本的组合，或从左到右和从右到左的区域设置时，在某些情况下，Kanzi Studio Localization Editor 呈现的文本与 Kanzi Studio Preview 不同。要微调文本，请在 Localization Editor 或 PO 文件中使用 Unicode 控制字符。

请参阅 Csv 插件示例。

要本地化文本资源：

在您的 Kanzi Studio 项目中使用 Text Block 节点创建文本内容，并将文本资源添加到本地化表中。请参阅添加资源至本地化表。
在 Library > Localization 中，右键单击包含您要本地化的资源的本地化表，然后选择 Export Localization Table。

Kanzi Studio 将本地化表模板导出到 <ProjectName>/Localization/<LocalizationTableName> 的一个 POT 文件，以及与该本地化表中的语言环境数量相同的多个 PO 文件。
- （可选）如果您想导出项目中的所有本地化表，请右键单击 Library > Localization 并选择 Export All Localization Tables。
  
  Kanzi Studio 导出到 <ProjectName>/Localization/<LocalizationTableName> 一个本地化表的 POT 模板文件，以及与所有本地化表中的语言环境数量相同的 PO 文件。
此步骤取决于您是首次翻译您的 Kanzi 应用程序，还是进行增量翻译：
- 如果您是第一次翻译您的 Kanzi 应用程序，请将 POT 文件发送给您的翻译人员。翻译人员为每个语言环境创建一个 PO 文件。
- 如果是更新翻译，请将每个地区的 POT 文件和 PO 文件发送给译员。
  
  每个 PO 文件仅包含已为该语言环境翻译的资源。要向 PO 文件中添加尚未为该语言环境翻译的资源，翻译人员需要使用 gettext 翻译编辑器从 POT 模板文件更新 PO 文件。
从译员那里收到 PO 文件之后，将它们保存到 <ProjectName>/Localization/<LocalizationTableName>。
在 Kanzi Studio 中，在 Library > Localization 中，右键单击翻译人员已本地化其内容的本地化表，然后选择 Import Localization Table。

Kanzi Studio 将 <ProjectName>/Localization/<LocalizationTableName> 目录中的所有 PO 文件导入到所选的本地化表中。
- （可选）如果您想手动选择要从中导入项目的 PO 文件的位置，请选择 Import Localization Table Manually。
- （可选）如果您想为项目中的所有本地化表导入 PO 文件，请在 Library 中右键单击 Localization 并选择 Import All Localization Tables。Kanzi Studio 会导入在 <ProjectName>/Localization 中找到的所有目录中的所有 PO 文件。

在本地化字符串中设置文本顺序¶

呈现信息的顺序在不同语言之间有所不同。Kanzi 允许您在本地化字符串中设置信息的顺序。

要设置本地化字符串中的文本顺序：

设置项目以进行本地化：
1. 创建一个显示本地化文本的节点。
  
  例如，创建一个 Text Block 2D 节点并将其命名为 PhotoDeletionMessage。
  
  请参阅使用 Text Block 节点。
2. 创建在本地化内容中使用的数据源或属性。
  
  例如，创建以下属性：
  - 数据类型为 Text 的 AlbumName。
  - 数据类型为 Integer 的 PhotoCount。
  请参阅创建属性类型。
3. 在 Node Tree 中，选择您之前创建的文本块节点。在 Properties 中，添加您创建的属性并设置：
  - AlbumName 到 New York
  - PhotoCount 到 10
4. 创建一个包含文本资源和语言环境的本地化表。
  
  例如，创建一个本地化表，并在其中：
  1. 添加一个文本资源并将其命名为 PhotoDeletionMessage。
  2. 创建区域设置 en-US 和 fi-FI。
  请参阅创建本地化表、添加资源至本地化表和使用 locales。
在 Localization Editor 中，为每个语言环境创建字符串。使用大括号 {} 作为占位符，用于插入您想从数据源或属性中插入的内容。

例如，在本地化表中创建这些本地化字符串：
- 对于 en-US
```
{} photos were deleted from the album {}
```
- 对于 fi-FI
```
Albumista {1} poistettiin {0} valokuvaa
```
在 fi-FI 区域设置中，您使用大括号内的索引来更改属性中的值在本地化文本中出现的顺序。您在下一步中创建的绑定中设置默认顺序。

使用大括号来表示 PO 文件中的本地化字符串。请参阅本地化文本资源。

在 Node Tree 中，选择显示本地化文本的节点。在 Properties 中，单击 + Add Binding，并在 Binding Editor 中设置：

Property 到 Text

Expression 到

# Use the acquire function to load the PhotoDeletionMessage text resource from
# the localization table using its resource ID, and cast it as a string type.
message = string(acquire("PhotoDeletionMessage"))

# Replace the placeholders in the localization strings with the values from
# the PhotoCount and AlbumName properties.
format(message, {@./PhotoCount}, {@./AlbumName})

单击 Save。

在 en-US 区域设置中，属性按照您传递给 format 函数的顺序显示。在 fi-FI 区域设置中，您可以使用大括号内的索引来更改参数的顺序。请参阅格式 (Format)。

../../_images/format-localized-text-node-tree-project-structure.png

../../_images/format-localized-text-properties-add-binding.png

../../_images/format-localized-text-create-binding.png

在 Node Tree 中，选择 Screen 节点，并在 Properties 中设置 Locale 属性。当您更改语言环境时，AlbumName 和 PhotoCount 属性会根据语言环境以不同的顺序出现。

../../_images/format-localized-text-demo.gif

本地化其他资源¶

除了将文本内容翻译成多种语言，Kanzi 还使您能够为每个区域使用不同的资源，包括动画、画刷、作曲器、字体、材质、网格、纹理和样式。

您可以使用此过程本地化所有类型的资源。

要本地化其他资源：

创建或导入内容到您的 Kanzi Studio 项目，并将此内容使用的资源添加到本地化表中。请参阅添加资源至本地化表。

例如，如果您拥有 5 个地区并希望为每个地区使用不同的一组纹理，请将每个地区纹理的图像导入到您的 Kanzi Studio 项目中。请参阅导入。
在 Library > Localization 中，双击包含您要本地化的资源的本地化表。

Kanzi Studio 在 Localization Editor 中打开本地化表。
在 Localization Editor 中，找到您要本地化的资源，双击您要本地化的语言环境中的资源单元格，然后输入文本或选择您要用于该语言环境的资源的资源 ID。
- 如果您未为某个区域选择资源或值，Kanzi 将使用该区域的默认资源或值。默认值列在 Default Value 列中。
- 要使用文件系统的资源，在要设置资源的单元格中选择 < URL >，并输入 file://，后跟文件系统中资源的绝对路径或相对路径。
重复上一步，直到为所有资源和地区选择了资源为止。

本地化主题¶

Kanzi 使您能够本地化主题应用程序。

要本地化主题：

对于每个您要将其内容本地化的主题，从包含要本地化的文本节点的内容创建预设件。请参阅创建和使用节点预设件。
本地化文本资源：
1. 在 Prefabs 中，选择您在上一步中创建的预设，并将其资源添加到本地化表中。
  
  请参阅添加资源至本地化表。
2. 在 Library > Localization 中，双击您在上一步中创建的本地化表以在 Localization Editor 中打开它，添加您想要本地化主题的语言环境，并本地化文本资源。请参阅本地化文本资源。
  
  要添加语言环境，请单击 + Create Locale，输入语言环境的名称，然后单击 OK。
使用 Prefab View 节点显示本地化内容：
1. 在 Prefabs 中，在您要显示本地化内容的节点下，创建一个 Prefab View 节点，并在 Properties 中添加并将 Prefab Template 属性设置为您在第一步中创建的预设之一。
  
  您必须使用 Prefab View 节点，以便可以动态更改 Prefab View 实例化的预设。请参阅 Prefab Placeholder 和 Prefab View 节点。
2. 在 Prefabs 中，右键单击您在上一步中创建的 Prefab View 节点，然后选择 Add Resources to a Theme Group。
3. 在 Add Resources to a Theme Group 窗口中：
  - 将 Theme Group 设置为您要添加资源的主题组。
    
    主题组包含有关哪个主题使用哪些资源的信息。
  - 将 Resource ID 重命名为在您的项目上下文中有意义的名称。
  单击 Add。
  
  Kanzi Studio 将资源 ID 添加到主题组，该资源 ID 指向在 Value 列中显示的预设。在您将资源添加到 Theme Group 的 Prefab View 节点中，Kanzi Studio 将 Prefab Template 属性的值设置为资源 ID。
4. （可选）在 Prefabs 中，将您在第 1 步中创建的 Prefab View 节点复制到您想要显示相同内容的位置。
5. 在 Library > Themes 中，双击您添加资源的主题组，并在您在步骤 3 中创建的资源 ID 的 Theme Editor 中为每个主题选择正确的预设。
在 Dictionaries 窗口中查看项目中本地化表和主题组的资源字典，点击 Locales and Themes，并选择不同的区域设置和主题以查看 Preview 中的本地化主题。

使用资源 ID 加载本地化资源¶

您可以使用资源 ID 加载本地化资源，这些 ID 是通过字符串属性定义的。例如，您可以设置一个节点以显示从数据源获取的资源 ID 所对应的本地化资源的内容。Kanzi 会自动显示应用程序当前语言环境的资源值。

使用资源 ID 加载本地化资源：

在 Kanzi Studio 中的本地化表中创建您希望在应用程序中显示的资源。

例如，为列表菜单中的标签创建文本资源。
创建一个数据源，其中字符串数据对象设置您要在应用程序中显示的资源的资源 ID。请参阅定义数据源和使用数据源。

例如：
1. 在 Kanzi Studio 的 Quick Start 窗口中，点击 Projects 并选择 Tutorials 选项卡。在 Data sources 教程旁边，点击。
2. 在 Library 中右键单击 Kanzi Engine Plugins，选择 Import Kanzi Engine Plugin，然后导入 <KanziWorkspace>/Tutorials/Data sources/Completed/Application/lib/Win64/GL_vs2019_Release_DLL/XML_data_source.dll Kanzi Engine 插件。
3. 在 Data Sources 中创建数据源。
  
  您使用该数据源为 List Box 节点中的项提供数据。请参阅教程：从数据源获取应用程序数据。
```
<menu type="list">
    <items>
        <item>
            <name type="string">Sounds</name>
        </item>
        <item>
            <name type="string">DateTime</name>
        </item>
        <item>
            <name type="string">Car</name>
        </item>
        <item>
            <name type="string">Display</name>
        </item>
        <item>
            <name type="string">Language</name>
        </item>
    </items>
</menu>
```
加载资源：
1. 使用 acquire 绑定函数根据资源 ID 加载资源。
  
  例如，选择 Text Block 节点，在该节点中您希望显示资源 ID 指向的内容，在 Properties 中单击 + Add Binding，并在 Binding Editor 中设置：
  - Property 到 Text
  - Expression 到
    acquire({DataContext.item.name})
  您将 Text 属性绑定到文本资源的内容，该文本资源的资源 ID 是您在 name 字符串数据对象的 menu 列表项中的数据源中定义的。
  
  小技巧
  
  您可以右键单击某个属性并选择 Create Binding，开始为该属性创建绑定。
  
  这样，您会自动将该属性添加到 Binding Editor 中。
2. 创建显示内容的节点，该内容是数据源中的资源 ID 所指向的内容。
  
  例如，将数据源的数据填充到 List Box 节点中，并将包含您添加了加载资源绑定的节点的预设用作项目模板。请参阅使用列表数据对象。

当您切换应用程序的区域设置时，acquire 绑定函数获取资源 ID 指向的资源，并更新文本。

编辑本地化的资源¶

在 Localization Editor 中，您可以设置和编辑区域设置使用的资源。

要编辑本地化的资源：

在 Library > Localization 中双击包含您要编辑的资源的本地化表。

Kanzi Studio 在 Localization Editor 中打开本地化表。
在 Localization Editor:
- 要编辑地区所使用的值，请右键点击资源的单元格，然后设置每个地区所使用的值。
  - 如果您未为某个区域选择资源或值，Kanzi 将使用该区域的默认资源或值。默认值列在 Default Value 列中。
    
    黑色单元格标记使用默认值的条目。
  - 要为文本资源使用空字符串，输入值，删除值，然后按下 Enter。
    
    灰色单元格标记使用空字符串的条目。
- 要添加语言环境，请单击 + Create Locale，输入语言环境的名称，然后单击 OK。
- 要手动为本地化表添加资源，请点击 + Add Resource 并选择：
  - Create 并选择您要创建的资源类型。
  - Add Existing 并选择一个已在您的项目中存在的资源。
- 要从工程中未使用的本地化表中删除资源 ID，请点击，选择要删除的资源 ID，然后点击 OK。
- 要从本地化表中删除资源 ID，请右键点击资源 ID 并选择 Delete Resource ID。
- 要只查看在 Node Tree 中被选中节点使用的资源 ID，请单击。
- 要将文本资源转换为任何其他资源类型和进行反向转换，请右键点击要转换的资源的行标题，然后选择 Convert to Resource 或 Convert to Text。
  
  请注意，您只能对空闲的资源转换资源类型。

在区域设置中使用资源的 kzb 文件 URL。¶

将您的工程中使用的资源添加到本地化表中之后，您可以使用一个 kzb URL 指向另一个 Kanzi Studio 工程中的资源。

要对地区中的资源使用 kzb 文件 URL：

在 Library > Localization 中，双击包含您要使用 kzb 文件 URL 的资源的本地化表。

Kanzi Studio 在 Localization Editor 中打开本地化表。
在 Localization Editor 中，双击资源的单元格，并在下拉菜单中选择 < URL >。
在单元格中，输入要使用的资源的 kzb 文件 URL。

例如，要使用来自另一个 Kanzi Studio 项目的字体，请输入指向该字体的 kzb 文件 URL。

创建地区包¶

语言环境包是一个仅包含特定语言环境资源的 kzb 文件。使用 Kanzi Engine API，您可以在设置该语言环境时加载特定语言环境使用的应用程序资源。这样可以减小应用程序中 kzb 文件的大小。

当您想要将由语言包使用的资源导出到主项目 kzb 文件时，在 Library 中选择资源，并在 Properties 中添加并启用 Is Used By Code 属性。所有启用了 Is Used By Code 属性的资源仅导出到主项目 kzb 文件，而不会导出到使用它们的任何语言包中。

要创建一个地区包：

在 Library > Localization 中，将您要添加到 Kanzi 应用程序的区域设置包中使用的资源添加到本地化表中。
在 Library > Localization 中，双击任何本地化表，并在 Localization Editor 中，点击您想要导出资源到本地包的语言环境名称旁边的。
在 Kanzi Studio 中，选择 File > Export > Export KZB。此命令：
- 为您在本地化表中标记为语言环境包的每个语言环境创建一个 kzb 文件。当 Kanzi Studio 导出语言环境包时，它会根据所包含资源的语言环境命名 kzb 文件。每个语言环境包文件仅包含该语言环境使用的资源。
- 创建包含整个 Kanzi Studio 项目的主 kzb 文件，但不包括您在本地化表中标记为语言环境包的语言环境资源。
- 将语言环境包 kzb 文件存储在 <ProjectName>/Application/bin/Locale_packs 目录中，或存储在您在 Project > Properties 中指定位置的 Locale_packs 目录中，在 Binary Export Directory 属性中。
使用 Kanzi Engine API 在您的 Kanzi 应用程序中加载语言环境包。请参阅

教程：本地化您的应用程序。

显示资源的使用情况¶

在 Localization Editor 中，您可以在 Node Tree 中查看当前选择的上下文中是否使用了资源以及它们的使用位置。

要显示资源的使用情况：

在 Library > Localization 中，双击您要检查资源使用情况的本地化表。

Kanzi Studio 在 Localization Editor 中打开本地化表。
使用 Localization Editor:
- 要在 Node Tree 中的本地化表中只显示当前选定上下文中的资源，请单击。
- 要列出使用了资源的节点，请右键点击资源 ID 并选择 Show Usage。

创建本地化表¶

您可以创建多个本地化表，以便：

保持资源类型分开。这使得大型项目的应用程序开发更容易。
根据应用程序的各个部分分离资源。当多个应用程序开发人员在同一个应用程序上工作时，每个人都可以为其应用程序的自己的区域拥有一个本地化表。
允许您将应用程序的不同部分的内容发送给译员。

要创建本地化表，在 Library 按 Alt 并右键单击 Localization 中，选择 Localization Table，并命名本地化表。

使用本地化在多个 Kanzi Studio 项目中组合成一个 Kanzi 应用程序。¶

要使用本地化功能，当您将多个 Kanzi Studio 项目合并到一个 Kanzi 应用程序中时，必须通过以下方式之一使本地化表对应用程序主项目的 Screen 节点可访问：

在应用程序的主工程中定义本地化表。
将引用项目中的本地化表合并到包含 Screen 节点的主项目中。然后，您可以使用资源 ID 从引用项目中的本地化表访问资源。请参阅合并工程。
请联系 Rightware 支持团队并请求 Kanzi Engine 插件，该插件使您能够在多个 Kanzi Studio 项目和 kzb 文件中使用本地化。请参阅提交支持请求。

另请参阅¶

将 Kanzi Studio 项目合并到 Kanzi 应用程序中。