i18n

GWT 包含一套灵活的工具，可以帮助您对应用程序和库进行国际化。GWT 国际化支持提供各种技术来国际化字符串、类型化值和类。

注意：要了解如何对示例 GWT 应用程序进行国际化，请参阅教程国际化 GWT 应用程序.

1. GWT 中的区域设置
2. 静态字符串国际化
3. 动态字符串国际化
4. Java 注解
5. 本地化属性文件

国际化快速入门

GWT 支持多种国际化代码的方式。首先研究哪种方法最符合您的开发要求。

• 您是否使用 UiBinder？

如果是，您可能需要了解有关UiBinder 的 I18n支持。

• 您是否从头开始编写代码？

  如果是，您可能需要了解有关 GWT 的静态字符串国际化技术。

• 您是否要存储非字符串本地化值？

  使用Constants或ConstantsWithLookup接口，它们允许类型，例如基本类型、字符串数组和字符串映射。

• 您是否需要将参数替换到翻译后的消息中？

  使用Messages.

• 您是否拥有想要重用的现有本地化属性文件？

  i18nCreator 工具可以自动生成扩展Constants、ConstantsWithLookup或Messages的接口。

• 您是否将 GWT 功能添加到现有 Web 应用程序中，该应用程序已经定义了本地化过程？

  Dictionary将帮助您与现有页面交互，而无需使用GWT 的区域设置概念.

• 您是否真的只想使用一种简单的方法将属性文件下载到客户端，无论是否本地化？

  您也可以做到这一点。尝试使用Constants，并且不使用任何特定于区域设置的属性文件。

国际化技术

GWT 提供了多种国际化技术，以最大限度地提高 GWT 开发人员的灵活性，并使他们能够以最有效、最易于维护、最灵活和最具互操作性的组合设计效率、可维护性、灵活性以及互操作性。

• 静态字符串国际化

  一组高效且类型安全的技术，它们依赖于强类型 Java 接口、属性文件以及代码生成，以提供特定于区域设置的消息和配置设置。这些技术依赖于接口Constants、ConstantsWithLookup和Messages.

• 动态字符串国际化

  一种简单灵活的技术，用于查找模块主机页面中定义的本地化值，而无需重新编译应用程序。此技术由类Dictionary支持。

• 扩展或实现 Localizable

  提供了一种使用特定于区域设置的类型替换来国际化算法集的方法。这是一种高级技术，您可能不需要直接使用它，尽管它对于实现复杂的国际化库很有用。有关此技术的详细信息，请参阅Localizable类文档。

I18N 模块

与国际化相关的核心类型

• LocaleInfo提供有关当前区域设置的信息。

• Constants用于本地化类型化常量值

• Messages用于本地化需要参数的消息

• ConstantsWithLookup类似于Constants，但对于高度数据驱动的应用程序而言，具有额外的查找灵活性

• Dictionary在将 GWT 模块添加到现有本地化网页时很有用

• Localizable在本地化封装在类中的算法或上述类无法提供足够的控制时很有用

• DateTimeFormat将日期格式化为字符串。请参阅有关日期和数字格式的部分。

• NumberFormat将数字格式化为字符串。请参阅有关日期和数字格式的部分。

GWT 中的区域设置

GWT 与大多数工具包不同，它在编译时而不是运行时执行大多数与区域设置相关的操作。这使 GWT 能够进行编译时错误检查，例如参数遗漏或翻译后的值类型不正确，并且优化可以考虑有关区域设置的已知事实。这也允许最终用户仅下载与他们相关的翻译。

有关在 GWT 应用程序中配置区域设置的详细信息，请参阅详细的区域设置文档.

静态字符串国际化

静态字符串国际化是在运行时性能方面本地化应用程序以适应不同区域设置的最有效方法。这种方法称为“静态”，因为它指的是在编译时创建与人类可读字符串匹配的标签。在编译时，会为模块中定义的所有语言创建标签和字符串之间的映射。模块启动序列使用延迟绑定根据区域设置设置映射适当的实现。

静态字符串本地化依赖于从标准 Java 属性文件或Java 源代码中的注释进行代码生成。GWT 通过三个标签接口（即没有表示功能契约的方法的接口）和一个代码生成库来支持静态字符串本地化，以生成这些接口的实现。

扩展 Constants 接口

Constants接口允许您以类型安全的方式本地化常量值，所有这些值都在编译时解析。以运行时开销为代价，您还可以通过 ConstantsWithLookup 接口允许按键名进行运行时查找。

使用 Messages 接口

Messages接口允许您将参数替换到消息中，甚至可以根据需要对不同区域设置的这些参数进行重新排序。属性文件中的消息格式遵循 Java MessageFormat中的规范。您创建的接口将包含一个 Java 方法，其参数与格式字符串中指定的参数匹配。

此外，Messages接口支持复数形式，以允许您的应用程序根据某物的数量准确地反映文本更改。

使用哪个接口？

以下是一些指导原则，可帮助您为应用程序的需求选择正确的接口

• 扩展Constants以创建各种类型常量值的集合，可以通过调用接口上的方法（称为常量访问器）来访问它们。常量访问器可以返回各种类型，包括字符串、数字、布尔值，甚至映射。会进行编译时检查以确保属性文件中的值与相应常量访问器声明的返回类型匹配。换句话说，如果常量访问器声明返回一个 int，则其关联的属性保证是一个有效的 int 值，从而避免了潜在的运行时错误来源。

• ConstantsWithLookup 接口与 Constants 接口相同，但它还包含一个用于按属性名称查找值的方法，这有助于在运行时按名称动态绑定到常量。ConstantsWithLookup 在高度数据驱动的应用程序中有时很有用。需要注意的是：ConstantsWithLookup 比 Constants 效率低，因为编译器无法丢弃未使用的常量方法，这会导致应用程序更大，并且查找无法在编译时解析。

• 扩展 Messages 创建一个可以接受参数的格式化消息集合。您可以将 Messages 接口视为传统 Java 中 Properties、ResourceBundle 和 MessageFormat 的组合的静态可验证等效项。

属性文件

以上所有类型都使用基于传统 Java 属性文件格式 的属性文件，尽管 GWT 使用 增强的属性文件格式，它允许 UTF-8，因此允许属性文件直接包含 Unicode 字符。

动态字符串国际化

对于可能不支持 GWT locale 客户端属性的现有应用程序，GWT 提供动态字符串国际化来轻松集成 GWT 国际化。

Dictionary 类允许您的 GWT 应用程序使用 主机 HTML 页面 提供的字符串。如果您现有的 Web 服务器具有您不想与 静态字符串国际化 方法集成的本地化系统，则此方法很方便。只需在 HTML 页面的主体中打印您的字符串作为 JavaScript 结构，您的 GWT 应用程序即可引用和显示它们给最终用户。由于它直接绑定到主机 HTML 中的键值对（无论它们是什么），因此 Dictionary 类对 GWT 本地化设置 不敏感。因此，生成本地化字符串的责任在于您的 Web 服务器。

动态字符串本地化允许您在运行时使用基于字符串的键查找 主机 HTML 页面中定义的本地化字符串。这种方法通常比静态字符串方法慢且更大，但不需要在消息更改或语言环境集更改时重新编译应用程序代码。

提示：Dictionary 类完全动态，因此它不提供静态类型检查，并且编译器无法检查无效键。这是我们建议尽可能使用 静态字符串国际化 的另一个原因。

Java 注解

指定 Constants 或 Messages 接口的默认值的推荐方法是使用 Java 注解。这种方法的优点是您可以将值保留在源代码中，因此在重构接口或在 IDE 中创建新方法时，更容易保持更新。此外，如果您使用的是自定义键生成器或为翻译生成输出文件，则需要使用注解。

此处讨论了所有地方都适用的注解 - 仅在 Constants 和 Messages 上使用的注解将在那里讨论。

类注解

以下注解适用于类或接口

• @DefaultLocale(String localeName) 指定此文件中包含的文本的语言环境。如果未指定，则默认为 en。

• @GeneratedFrom(String fileName) 指示此文件是从提供的文件生成的。请注意，不需要此文件名在编译时可解析，因为此文件可能是在不同的机器上生成的等等。如果生成器检查源文件（例如，以查看是否已过时），则如果文件不存在或名称不可解析，则不应发出任何警告。

• @GenerateKeys(String generatorFQCN) 请求使用指定的生成器生成每个方法的键（见下文）。如果未提供此注解，则键将为方法的名称，如果指定但没有参数，则将默认为 MD5 实现。

指定的生成器类必须实现 KeyGenerator 接口。通过指定完全限定的类名，这将扩展到 GWT 命名空间中不存在的其他格式。用户只需确保指定的类在编译时位于类路径上即可。这允许与非标准或内部工具集成，这些工具可能使用自己的哈希函数来合并来自多个应用程序的重复翻译字符串，或者以其他方式需要与外部工具兼容。

使用包含完全限定类名的字符串而不是类文字，因为键生成算法可能会提取不可翻译的代码，因此无法在客户端代码中直接看到。

如果未提供此注解，则键将为方法的简单名称。

• @Generate(String[] formatFQCN, String filename, String[] locales) 请求在编译过程中生成消息目录文件。如果未提供文件名，则使用基于接口名称的默认名称。输出文件创建在 -out 目录下。格式名称是实现 MessageCatalogFormat 接口的完全限定类名。例如，这可以根据此文件中包含的信息生成 XLIFF 或属性文件。特定 MessageCatalogFormat 实现可能会为该 MessageCatalogFormat 需要额外的参数定义额外的注解。

如果指定了任何语言环境，则仅生成列出的语言环境。如果只列出了一个语言环境，则将精确使用提供的（或生成的）文件名；否则，locale 将添加到文件扩展名之前。

使用包含完全限定类名的字符串而不是类文字，因为消息目录实现可能会提取不可翻译的代码，因此无法在客户端代码中直接看到。

方法注解

以下注解适用于方法

• @Key(String key) 指定在此特定方法的外部格式中使用的键。如果未提供，它将根据上面讨论的 @GenerateKeys 注解生成。
• @Description(String desc) 文本的描述。请注意，这不包含在文本的哈希中，并且根据文件格式，可能不会以翻译者可见的方式包含在其中。
• @Meaning(String meaning) 提供与该文本相关的含义。此信息提供给翻译者，以便区分不同的可能翻译 - 例如，orange 的含义可以是“水果”或“颜色”。请注意，具有相同文本但不同含义的两个消息应具有不同的键，因为它们可能被翻译成不同的内容。

本地化属性文件

静态字符串国际化 使用传统的 Java .properties 文件来管理将标签翻译成本地化值。这些文件可以放在与主模块类相同的包中。它们必须放在与其对应的 Constants/Messages 子接口定义文件相同的包中。

提示：使用 i18nCreator 脚本开始使用。

$ i18nCreator -eclipse Foo com.example.foo.client.FooConstants
  Created file src/com/example/foo/client/FooConstants.properties
  Created file FooConstants-i18n.launch
  Created file FooConstants-i18n

Constants 和 Messages 都使用传统的 Java 属性文件，但有一个显着区别：与 GWT 一起使用的属性文件应以 UTF-8 编码，并且可以包含 Unicode 字符，从而避免使用 native2ascii。有关示例和格式详细信息，请参见上述接口的 API 文档。

为了使用国际化字符，请确保您的主机 HTML 页面以 UTF-8 形式提供，最简单的方法是在页面的头部包含一个 meta 标签

<meta charset="utf-8" />

您还必须确保在 IDE 中将所有相关的源文件和 .properties 文件设置为 UTF-8 字符集。