本章介绍如何用 Text Messages、Application Translations、XLIFF 导出导入和 App Builder 内置编辑工具，把 APEX 应用交付给不同语言的用户。核心思路是：应用仍以主语言维护，APEX 把可翻译界面文本集中为 Text Message，再按用户语言选择对应译文。

22 翻译应用#

APEX 的多语言机制围绕 Text Messages 和 Application Translations 展开。开发者可以随时同步应用翻译，把页面中直接输入的文字替换为 Text Message 引用；也可以在 Page Designer 中通过 Text Messages Picker 复用已有消息。翻译阶段既可以导出 XLIFF 交给外部翻译流程批量处理，也可以在 App Builder 的可筛选网格里直接维护译文。

学习前提：已经有一个可以运行的示例应用，例如官方章节中的 Woods HR 应用；应用主语言为英语，并包含 Employee Directory 页面及员工详情抽屉页。后续步骤都在 App Builder 的 Shared Components、Globalization Attributes、Application Translations、Text Messages 和 Page Designer 中完成。

验证目标：添加意大利语后，用户的浏览器语言或应用语言设置可以驱动登录页、导航、报表列标题、表单标签和新增文本显示为意大利语译文。

来源：Translating Your Application

22.1 查看需要翻译的 Woods HR 页面#

APEX 应用先用一个主语言创建。官方 Woods HR 示例使用英语，示例规模很小：一个 Employee Directory 页面，页面中有 Interactive Report 区域；再配一个相关的员工详情表单页。应用规模变大时，翻译机制仍然相同，只是 Text Message 数量更多。

图 22-1 主语言中的 Employee Directory 页面，报表标题、列标题、按钮和导航文本都属于后续可能翻译的界面文本。

HR 代表从目录页进入员工详情抽屉页，用于查看和编辑员工信息。这个页面中的表单项标签、按钮、区域标题和说明文本也需要进入同一套翻译流程。

图 22-2 员工详情抽屉页只面向 HR 代表，但仍应与目录页使用一致的术语和译文。

操作检查：先以主语言运行应用，记录目录页、员工详情页、登录页和导航菜单中的可见文字。后续每次同步或导入译文后，都回到这些页面确认同一批文字是否被转换、翻译并一致显示。

来源：Exploring Woods HR Pages to Translate

22.2 启用第一个翻译语言#

决定为应用增加第一种译文语言时，进入 Shared Components > Globalization Attributes，启用 Translate Application。官方示例选择 Text Message-Based，这是最简单的方式，也能在 App Builder 和 Page Designer 中获得最好支持。

图 22-3 在 Globalization Attributes 中启用应用翻译，并使用 Text Message-Based 方案。

接着进入 Shared Components > Application Translations，点击 Add Language。如果一部分最终用户需要意大利语界面，可以新增 Italian (Italy) (it) 作为目标语言。

图 22-4 在 Application Translations 中添加第一个目标语言，例如 Italian (Italy) (it)。

语言创建后，列表中会同时显示应用主语言和新增的目标语言。添加第一个语言时，App Builder 会自动执行一次文本消息同步，为应用中已发现的可翻译文字创建 Text Message，并为目标语言创建对应条目。

图 22-5 新增语言后，应用支持的语言列表中出现主语言和目标语言，并完成初次同步。

验证检查：Application Translations 页面应显示目标语言；Text Messages 中应出现从页面标题、列标题、项标签等界面文本生成的消息。此时目标语言条目通常仍保留主语言文本，等待后续翻译。

来源：Enabling the First Translation Language

22.3 理解初次 Text Message 同步#

添加第一种应用翻译语言时，App Builder 会扫描所有页面，为每一个唯一的可翻译字符串创建 Text Message 组件，并把原来直接写在属性里的文字改成对应消息引用。它还会为新增目标语言创建每条消息的镜像条目。这个过程称为同步应用的可翻译文本，首次添加语言时自动发生，之后也可以按需手动触发。

例如，Employee Directory 页面的 Title 属性最初只是直接输入的 Employee Directory。添加第一种翻译语言后，该属性改为引用名为 EMPLOYEE_DIRECTORY 的 Text Message，语法如下；Page Designer 的 Property Editor 会在属性下方显示当前翻译后的文本。

&{EMPLOYEE_DIRECTORY}.
图 22-6 页面标题从内联文本变为 Text Message 引用，属性编辑器仍显示当前语言的可读文本。

同一页面中的报表列标题也会经历相同转换。官方示例中 HIREDATE 等列标题会被替换为 Text Message 引用。

图 22-7 报表列标题等可翻译属性同样被转换为 Text Message 引用。

如果完全相同的文本出现在多个页面，APEX 会把所有用法更新为引用同一个 Text Message。示例中 Employee 页面上的 P3_HIREDATE 页面项，也使用同一个 DATE_OF_HIRE 消息。

图 22-8 相同原文会集中到同一个 Text Message，减少重复翻译和术语不一致。

验证检查：在 Page Designer 中打开同步后的页面，确认标题、列标题、项标签等属性不再是裸文本，而是 &{MESSAGE_NAME}. 形式；相同业务含义的文本应尽量复用同一个消息。

来源：Understanding Initial Text Message Sync

22.4 导出与导入翻译#

可以逐条编辑意大利语消息，但实际项目更常见的是批量翻译。APEX 支持用标准的 XML Localization Interchange Format（XLIFF）导出和导入 Text Messages。进入 Application Translations 页面，在目标语言行的三点菜单中选择 Export as XLIFF，即可导出该语言待翻译消息。

图 22-9 在目标语言的三点菜单中导出 XLIFF 文件，用于批量翻译。

XLIFF 文件名包含应用 ID、源语言和目标语言。例如 Woods HR 应用 ID 为 154，英语源语言、意大利语目标语言的文件名是 f154_en_it.xlf。翻译前，<target> 通常与对应 <source> 相同。

<?xml version="1.0"?>
<xliff version="1.0">
  <file original="f154_en_it.xlf" source-language="en" target-language="it" datatype="html">
    <trans-unit id="EMPLOYEE_DIRECTORY">
      <source>Employee Directory</source>
      <target>Employee Directory</target>
    </trans-unit>
    <trans-unit id="DATE_OF_HIRE">
      <source>Date of Hire</source>
      <target>Date of Hire</target>
    </trans-unit>
    ⋮
  </file>
</xliff>

通常会把该文件交给翻译服务或翻译管理系统。返回文件中，<target> 元素会被替换为目标语言译文，例如：

<?xml version="1.0"?>
<xliff version="1.0">
  <file original="f154_en_it.xlf" source-language="en" target-language="it" datatype="html">
    <trans-unit id="EMPLOYEE_DIRECTORY">
      <source>Employee Directory</source>
      <target>Elenco dipendenti</target>
    </trans-unit>
    <trans-unit id="DATE_OF_HIRE">
      <source>Date of Hire</source>
      <target>Data di assunzione</target>
    </trans-unit>
    ⋮
  </file>
</xliff>

导入时回到 Application Translations 页面，点击 Import Text Messages，选择翻译后的 XLIFF 文件。导入后，目标语言 Text Message 的译文会更新。

图 22-10 使用 Import Text Messages 把翻译后的 XLIFF 应用到目标语言。

交付检查：不要修改 trans-unit 的消息标识，不要破坏 XML 结构。交给译员时应同时提供术语表、页面截图和测试账号；孤立字符串很容易误译，尤其是短按钮、列标题和带占位符的消息。

来源：Exporting and Importing Translations

22.5 决定用户的首选语言#

在应用的 Globalization Attributes 中，需要选择应用如何判断当前用户应使用哪种语言。官方列出四种方式：

  • 会话语言：通过 APEX_UTIL.SET_SESSION_LANG 或应用 URL 参数 P_LANG 设置。
  • Web 浏览器语言偏好：根据用户浏览器设置推断语言。
  • 用户偏好：通过 APEX_UTIL.SET_PREFERENCE 设置 FSP_LANGUAGE_PREFERENCE。
  • 应用项：使用 FSP_LANGUAGE_PREFERENCE 应用项。

例如选择 Browser 时，APEX 会根据用户浏览器语言设置推断运行语言。这个选择会影响登录页、导航、页面标题、报表列、按钮和运行时消息等可翻译文本。

图 22-11 在 Globalization Attributes 中配置当前用户语言的推导方式。

验证检查：如果选择 Browser，把浏览器首选语言调整为意大利语后重新访问应用；如果选择会话或用户偏好，则分别验证 URL 参数、API 设置或用户偏好值是否能改变页面语言。

来源：Determining User's Preferred Language

22.6 以另一种语言体验应用#

当用户的语言偏好匹配目标语言并且译文已经导入后，运行时界面会按该语言显示。官方示例中，HR 代表 Susan 的浏览器偏好设置为意大利语，她登录应用时会看到意大利语登录页。

图 22-12 用户浏览器偏好为意大利语时，登录页显示对应译文。

进入应用后，导航菜单和 Employee Directory 页面也会显示为意大利语。这里验证的不只是单个页面标题，还包括导航、报表标题、列标题和页面动作等不同位置的文本。

图 22-13 导航菜单和 Employee Directory 页面使用已导入的意大利语译文。

Susan 编辑员工 ALLEN 时，员工详情抽屉页也显示一致的意大利语译文。这个检查能发现只翻译了列表页、但遗漏表单页或弹窗页的问题。

图 22-14 员工详情抽屉页也应显示一致的目标语言译文。

验收建议：用同一个用户从登录到列表、再到详情页走完整路径。确认各处语言一致，且翻译后文本没有造成按钮、列标题或表单布局溢出。

来源：Experiencing App in Another Language

22.7 应用演进时继续翻译文本#

应用上线后仍会持续新增页面、按钮、说明和区域。新增可翻译文本有两种同样有效的做法：先创建 Text Message，再在页面中引用它；或者在新增页面和页面元素时先直接输入文本。之后可以随时执行 Sync Text Messages，自动把新文本准备进下一轮翻译。

选择建议：如果文本会在多个位置复用，或需要一个稳定、可读的消息键，优先先建 Text Message。若只是快速新增一次性页面内容，可以先内联输入，随后通过同步让 APEX 自动创建消息。

来源：Translating Text as Your App Evolves

22.7.1 添加新的 Text Message#

如果要在 Employee 页面新增 Increase Salary 按钮，可以先创建一个名为 INCREASE_SALARY 的 Text Message，主语言文本为 Increase Salary。这样消息键由开发者明确命名，后续在多个按钮、确认消息或帮助文本中复用时更可控。

图 22-15 先创建 Text Message，可以为新的可翻译界面文本选择有意义的消息键。

验证检查：在 Shared Components 的 Text Messages 中应能搜索到 INCREASE_SALARY；主语言文本应为 Increase Salary，目标语言可在同步后补齐或手动维护。

来源：Adding a New Text Message

22.7.2 使用 Text Messages Picker#

可以把 INCREASE_SALARY 用作 Employee 页面中新按钮的标签。先确认 Text Messages Picker 已启用。它是一个地球图标按钮，会出现在包含可翻译文本的属性旁边。如果看不到这些按钮，可通过工具栏的扳手下拉菜单启用 Show > Text Messages Picker。

图 22-16 启用 Text Messages Picker 后，可翻译属性旁会显示地球图标。

启用后，点击属性旁的地球图标，搜索并选择要使用的 Text Message。

图 22-17 通过 Text Messages Picker 搜索并选择已有消息。

Text Messages Picker 会自动把所选消息按正确替换语法填入属性，例如 &{INCREASE_SALARY}.，并在下方显示当前语言解析后的文本 Increase Salary。

图 22-18 Picker 会生成正确的 Text Message 替换语法，并显示解析后的文本。

Text Message 也可以包含占位符。例如：

Your salary increase is %pct percent, and starts %date

这种情况下，Picker 会显示占位符名称，方便输入静态值或动态值。若需要使用 !RAW 这类替换修饰符，它位于右花括号之后、最后的点之前。

  • &{INCREASE_SALARY}.
  • &{INCREASE_SALARY pct="5" date="&P3_SOME_ITEM."}.
  • &{INCREASE_SALARY pct="5" date="&P3_SOME_ITEM."}!RAW.

验证检查：运行页面后，新按钮应显示当前语言对应的译文；如果消息含占位符，应确认替换值正确出现，且没有多余转义或未解析的占位符。

来源：Using the Text Messages Picker

22.7.3 直接内联输入新文本#

也可以继续在页面属性中直接输入文字。例如新增需求要求在 Employee 表单顶部放一个数据隐私说明区域。开发者可以先在页面中新增 Data Privacy 静态内容区域，并直接填写区域 Title 和 HTML Code。图中选中了组件树里的 Data Privacy 静态内容区域，并标出 Title 与 HTML Code 都仍是以应用基础语言直接输入的文字。

图 22-19 直接内联输入的新文本，会在下一次同步时被创建为 Text Message。

验证检查：同步前，Page Designer 中可以看到属性仍是直接文本；同步后，这些属性应被替换为 &{...}. 引用，并在 Text Messages 中出现对应新消息。

来源：Entering New Text Directly Inline

22.8 随时同步 Text Messages#

准备翻译新增文本时，在 Application Translations 页面目标语言行的三点菜单中选择 Sync Text Messages，然后在对话框中点击 Synchronize。官方示例中，这次同步会完成四类工作：

  • 为已有的 INCREASE_SALARY 消息补充缺失的意大利语版本。
  • 为直接输入的新文本创建主语言 Text Message，例如 DATA_PRIVACY 和 PLUG_SOURCE。
  • 把 Employee 页面中的新文本替换为 Text Message 替换语法。
  • 把这两个新消息复制到意大利语条目中，初始值为主语言文本，等待翻译。

注意：如果只想把应用中的字面文本转换为 Text Messages，而不执行基础语言与目标语言之间的同步，可以使用同一页面中的 Convert to Text Messages。对目标语言执行同步时，App Builder 会隐式先做这一步，再同步基础语言和目标语言。

图 22-20 同步会补齐目标语言缺失消息，并把新增内联文本转换为 Text Message。

验证检查：同步完成后，Text Messages 中应能找到 INCREASE_SALARY、DATA_PRIVACY 和 PLUG_SOURCE 的目标语言条目；Page Designer 中新增内联文本应已改为消息引用。

来源：Synchronizing Text Messages Anytime

22.9 在可筛选网格中编辑翻译#

缺失译文可以再次导出 XLIFF 交给外部翻译服务，也可以直接在 APEX 中维护。对于少量内部更新，Text Messages 页面的 Grid Edit 很方便，可以一次编辑多条消息的目标语言文本。

图 22-21 从 Text Messages 页面进入 Grid Edit，用于批量修改消息文本。

按语言筛选后，可以为刚新增的三条消息录入意大利语译文，然后点击 Save 保存。

图 22-22 通过语言筛选后，可以集中编辑多条目标语言译文。

保存最新文本的意大利语译文后，Susan 这类使用意大利语运行应用的用户，会在页面上看到这些更新后的目标语言文本。

图 22-23 手动维护并保存的目标语言译文，会在运行时向对应语言用户显示。

适用边界：Grid Edit 适合少量、内部可控的翻译修正。若涉及大量字符串、多名译员、审批流程或术语库，仍应优先使用 XLIFF 和专业翻译流程。

来源：Editing Translations in a Filterable Grid

22.10 集中管理可复用界面文本#

即使应用暂时不需要多语言，把可复用界面文本集中到 Text Messages 也有价值。可以按需把每个复用字符串转换为某个 Text Message，例如 SOMENAME，然后用 &{SOMENAME}. 替换原始文字。在 Page Designer 中也可以通过地球图标选择已有消息。

如果希望批量转换所有可翻译属性中的文本，可以进入 Shared Components > Text Messages，在 Tasks 区域点击 Convert Application Text。在对话框中点击 Convert Text Messages 后，App Builder 会创建所需的新 Text Messages，并把原始文本替换为对应替换语法。

提示：可以重复运行 Convert Application Text，把上次转换后新增的字符串继续集中为 Text Messages。

图 22-24 Convert Application Text 可以批量把应用文本集中为 Text Messages。

工程实践：对按钮、导航、常用提示、隐私说明等高复用文本，先命名 Text Message 再引用，能降低重复翻译和术语漂移。对一次性文本，也应在发布前同步并检查目标语言是否补齐。

来源：Centralizing Reusable UI Text