4.5. 国际化和本地化

1. 如果您还没有这样做，请将您的 Maven 设置配置为使用 JBoss EAP Maven 存储库。

   如需更多信息，请参阅使用 Maven 设置配置 JBoss EAP Maven 存储库。

2. 配置项目的 pom.xml 文件，以使用 JBoss Logging 工具。

   详情请查看 JBoss Logging Tools Maven 配置。

3. 通过添加 Java 接口到项目来创建消息日志记录器接口，以包含日志消息定义。

   指出用于描述它将定义的日志消息的接口。日志消息接口有以下要求：

   • 它必须标有 @org.jboss.logging.annotations.MessageLogger。
   • 另外，还可扩展 org.jboss.logging.BasicLogger。

   • 接口必须定义一个字段，该字段是与接口相同的类型的消息日志记录器。使用 @org.jboss.logging. Logger 的 getMessageLogger （） 方法执行此操作。

     示例：创建消息日志器

     package com.company.accounts.loggers;
     
     import org.jboss.logging.BasicLogger;
     import org.jboss.logging.Logger;
     import org.jboss.logging.annotations.MessageLogger;
     
     @MessageLogger(projectCode="")
     interface AccountsLogger extends BasicLogger {
        AccountsLogger LOGGER = Logger.getMessageLogger(
              AccountsLogger.class,
              AccountsLogger.class.getPackage().getName() );
     }

     Copy to Clipboard Toggle word wrap

4. 向接口添加一个方法定义，以用于每一日志消息。

   请以描述性方式命名每个方法，使其表示的日志消息。每个方法都有以下要求：

   • 该方法必须返回 void。
   • 它必须标有 @org.jboss.logging.annotation.LogMessage 注释。
   • 它必须标有 @org.jboss.logging.annotations.Message 注释。
   • 默认日志级别为 INFO。

   • @org.jboss.logging.annotations.Message 的 value 属性包含默认日志消息，如果没有可用的翻译则使用此消息。

     @LogMessage
     @Message(value = "Customer query failed, Database not available.")
     void customerQueryFailDBClosed();

     Copy to Clipboard Toggle word wrap

5. 在您的代码中添加调用，以从其中记录消息来调用，从而调用方法。

   无需创建接口实施，注释处理器会在编译项目时为您执行此操作。

   AccountsLogger.LOGGER.customerQueryFailDBClosed();

   Copy to Clipboard Toggle word wrap

   自定义日志记录器从 BasicLogger 子级，因此也可以使用 BasicLogger 的日志记录方法。不需要创建其他日志记录器来记录非国际化的消息。

   AccountsLogger.LOGGER.error("Invalid query syntax.");

   Copy to Clipboard Toggle word wrap
6. 该项目现在支持一个或多个可本地化的国际化日志记录器。

1. 如果您还没有这样做，请将您的 Maven 设置配置为使用 JBoss EAP Maven 存储库。如需更多信息，请参阅使用 Maven 设置配置 JBoss EAP Maven 存储库。
2. 配置项目的 pom.xml 文件，以使用 JBoss Logging 工具。详情请查看 JBoss Logging Tools Maven 配置。

3. 为异常创建一个接口。JBoss 日志工具在接口中定义国际化的消息。为每个接口命名其包含的消息的描述性。接口有以下要求：

   • 必须将其声明为 公开。
   • 它必须标有 @org.jboss.logging.annotations.MessageBundle。

   • 接口必须定义与接口相同的消息捆绑包的字段。

     示例：创建一个 消息捆绑包 接口

     @MessageBundle(projectCode="")
     public interface GreetingMessageBundle {
        GreetingMessageBundle MESSAGES = Messages.getBundle(GreetingMessageBundle.class);
     }

     Copy to Clipboard Toggle word wrap

     注意

     调用 Messages.getBundle(GreetingMessagesBundle.class) 等同于调用 Messages.getBundle（GreetingMessagesBundle.class, Locale.getDefault（））。

     locale .getDefault（） 获取 Java 虚拟机此实例的默认区域设置的当前值。Java 虚拟机会根据主机环境设置启动过程中的默认区域设置。如果未明确指定区域设置，它将被许多区域敏感方法使用。它可以通过 setDefault 方法更改。

     如需更多信息 ，请参阅《JBoss EAP 配置指南》 中设置服务器的默认 区域。

4. 向每条消息的接口添加一个方法定义。请以描述性方式命名每个方法，使其表示的消息。每个方法都有以下要求：

   • 它必须返回类型为 String 的对象。
   • 它必须标有 @org.jboss.logging.annotations.Message 注释。

   • @org.jboss.logging.annotations.Message 的 value 属性必须设置为 default 消息。这是如果没有可用的翻译，则会使用的消息。

     @Message(value = "Hello world.")
     String helloworldString();

     Copy to Clipboard Toggle word wrap

5. 在应用程序中调用需要获取消息的接口方法：

   System.out.println(helloworldString());

   Copy to Clipboard Toggle word wrap

1. 配置项目的 pom.xml 文件，以使用 JBoss Logging 工具。详情请查看 JBoss Logging Tools Maven 配置。

2. 为异常创建一个接口。JBoss 日志工具在接口中定义了国际化的异常。为每个接口命名其定义的异常的描述性。接口有以下要求：

   • 必须将其声明为 公开。
   • 它必须标有 @MessageBundle。

   • 接口必须定义与接口相同的消息捆绑包的字段。

     示例：创建一个 例外捆绑包 接口

     @MessageBundle(projectCode="")
     public interface ExceptionBundle {
        ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);
     }

     Copy to Clipboard Toggle word wrap

3. 为每个例外向接口添加一个方法定义。以描述性方式命名每个方法表示的异常。每个方法都有以下要求：

   • 它必须返回 例外 对象或子类型 例外。
   • 它必须标有 @org.jboss.logging.annotations.Message 注释。
   • @org.jboss.logging.annotations.Message 的 value 属性必须设置为默认异常消息。这是如果没有可用的翻译，则会使用的消息。

   • 如果返回的异常具有除消息字符串外还需要参数的构造器，则必须使用 @Param 注释在方法定义中提供这些参数。这些参数的类型和顺序必须与在异常的结构中相同。

     @Message(value = "The config file could not be opened.")
     IOException configFileAccessError();
     
     @Message(id = 13230, value = "Date string '%s' was invalid.")
     ParseException dateWasInvalid(String dateString, @Param int errorOffset);

     Copy to Clipboard Toggle word wrap

4. 在您需要获得其中一个例外的地方，调用代码中的接口方法。方法不会抛出异常，它们返回异常对象，然后您可以抛出它。

   try {
      propsInFile=new File(configname);
      props.load(new FileInputStream(propsInFile));
   }
   catch(IOException ioex) {
     //in case props file does not exist
      throw ExceptionBundle.EXCEPTIONS.configFileAccessError();
   }

   Copy to Clipboard Toggle word wrap

生成转换属性文件

1. 通过将 -AgenereatedTranslationFilePath 编译器参数添加到 Maven 编译器插件配置来添加 Maven 配置，并为它分配创建新文件的路径。

   此配置会在 Maven 项目的 target/generated-translation-files 目录中创建新文件。

   示例：定义转换文件路径

   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>2.3.2</version>
      <configuration>
         <source>1.6</source>
         <target>1.6</target>
         <compilerArgument>
         -AgeneratedTranslationFilesPath=${project.basedir}/target/generated-translation-files
         </compilerArgument>
         <showDeprecation>true</showDeprecation>
      </configuration>
   </plugin>

   Copy to Clipboard Toggle word wrap

2. 使用 Maven 构建项目：

   $ mvn compile

   Copy to Clipboard Toggle word wrap

   为标有 @MessageBundle 或 @Message Logger 的每个接口创建了一个属性文件。

   • 新文件创建在与声明每个接口的 Java 软件包对应的子目录中。

   • 每一新文件采用以下模式命名，其中 INTERFACE_NAME 是用于生成文件的接口的名称。

     INTERFACE_NAME.i18n_locale_COUNTRY_VARIANT.properties

     Copy to Clipboard Toggle word wrap

转换国际化的日志记录器、例外或消息

1. 运行以下命令来创建模板转换属性文件：

   $ mvn compile

   Copy to Clipboard Toggle word wrap
2. 将您要从创建它们的目录中转换的接口模板复制到项目的 src/main/resources 目录中。属性文件必须与要转出的接口位于同一个软件包中。
3. 重命名复制的模板文件，以指明它将包含的语言。例如： GreeterLogger.i18n_fr_FR.properties。

4. 编辑新转换属性文件的内容，使其包含适当的翻译：

   # Level: Logger.Level.INFO
   # Message: Hello message sent.
   logHelloMessageSent=Bonjour message envoyé.

   Copy to Clipboard Toggle word wrap
5. 重复复制模板的过程，并根据捆绑包中的每个转换进行修改。

先决条件

1. 您必须已拥有含有国际化日志消息的项目。详情请查看 创建国际化的日志消息。
2. 您需要知道您将要使用的项目代码。您可以使用单个项目代码，或者为每个接口定义不同的项目代码。

添加消息 ID 和项目代码到日志消息

1. 利用附加至自定义日志记录器接口的 @MessageLogger 注释的 projectCode 属性，指定接口的项目代码。接口中定义的所有消息都将使用该项目代码。

   @MessageLogger(projectCode="ACCNTS")
   interface AccountsLogger extends BasicLogger {
   
   }

   Copy to Clipboard Toggle word wrap

2. 利用附加至消息方法的 @Message 注释的 id 属性，指定每条消息的消息 ID。

   @LogMessage
   @Message(id=43, value = "Customer query failed, Database not available.")  void customerQueryFailDBClosed();

   Copy to Clipboard Toggle word wrap

3. 如果日志消息同时关联了消息 ID 和项目代码，这些日志消息会将它们添加到记录的消息中。

   10:55:50,638 INFO  [com.company.accounts.ejb] (MSC service thread 1-4) ACCNTS000043: Customer query failed, Database not available.

   Copy to Clipboard Toggle word wrap

1. 将 level 属性添加到日志消息方法定义的 @LogMessage 注释。

2. 利用 level 属性，分配此消息的日志级别。level 的有效值是在 org.jboss.logging.Logger.Level:DEBUG、ERROR、FATAL、INFO、TRACE 和 WARN 中定义的六个常量。

   import org.jboss.logging.Logger.Level;
   
   @LogMessage(level=Level.ERROR)
   @Message(value = "Customer query failed, Database not available.")
   void customerQueryFailDBClosed();

   Copy to Clipboard Toggle word wrap

使用参数自定义日志消息

1. 向方法定义中添加任何类型的参数。无论类型如何，参数的 String 表示法就是消息中显示的内容。

2. 添加对该日志消息的参数引用。参考可以使用显式或普通索引。

   • 要使用普通索引，请在您希望显示每个参数的消息字符串中插入 %s 字符。%s 的第一个实例将插入第一个参数，第二个实例将插入第二个参数，以此类推。
   • 要使用显式索引，请在消息中插入 %#$s 字符，其中 # 代表您要显示的参数数。

指定一个例外作为日志消息的 Causeion

1. 向方法添加类型为 可 浏览或其子类的参数。

   @LogMessage
   @Message(id=404, value="Loading configuration failed. Config file:%s")
   void loadConfigFailed(Exception ex, File file);

   Copy to Clipboard Toggle word wrap

2. 添加 @Cause 注释到 参数。

   import org.jboss.logging.annotations.Cause
   
   @LogMessage
   @Message(value = "Loading configuration failed. Config file: %s")
   void loadConfigFailed(@Cause Exception ex, File file);

   Copy to Clipboard Toggle word wrap

3. 调用 方法。在您的代码中调用该方法时，必须传递一个正确类型的对象，并在日志消息后显示该方法。

   try
   {
      confFile=new File(filename);
      props.load(new FileInputStream(confFile));
   }
   catch(Exception ex) //in case properties file cannot be read
   {
        ConfigLogger.LOGGER.loadConfigFailed(ex, filename);
   }

   Copy to Clipboard Toggle word wrap

先决条件

1. 您必须已有具有国际化例外的项目。详情请查看 创建国际化例外。
2. 您需要知道您将要使用的项目代码。您可以使用单个项目代码，或者为每个接口定义不同的项目代码。

添加消息 ID 和项目代码到例外消息

1. 使用附加至异常捆绑包接口的 @MessageBundle 注释的 projectCode 属性来指定项目代码。接口中定义的所有消息都将使用该项目代码。

   @MessageBundle(projectCode="ACCTS")
   interface ExceptionBundle
   {
      ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);
   }

   Copy to Clipboard Toggle word wrap

2. 使用与定义异常的方法关联的 @Message 注释的 id 属性，指定各个异常的消息 ID。

   @Message(id=143, value = "The config file could not be opened.")
   IOException configFileAccessError();

   Copy to Clipboard Toggle word wrap

使用参数自定义例外消息

1. 向方法定义中添加任何类型的参数。无论类型如何，参数的 String 表示法就是消息中显示的内容。

2. 添加对异常消息的参数引用。参考可以使用显式或普通索引。

   • 要使用普通索引，请在您希望显示每个参数的消息字符串中插入 %s 字符。%s 的第一个实例将插入第一个参数，第二个实例将插入第二个参数，以此类推。
   • 要使用显式索引，请在消息中插入 %#$s 字符，其中 # 代表您要显示的参数数。

1. 向方法添加类型为 可 浏览或其子类的参数。

   @Message(id=328, value = "Error calculating: %s.")
   ArithmeticException calculationError(Throwable cause, String msg);

   Copy to Clipboard Toggle word wrap

2. 添加 @Cause 注释到 参数。

   import org.jboss.logging.annotations.Cause
   
   @Message(id=328, value = "Error calculating: %s.")
   ArithmeticException calculationError(@Cause Throwable cause, String msg);

   Copy to Clipboard Toggle word wrap

3. 调用 interface 方法以获取异常对象。最常见的用例是从 catch 块中抛出新的异常，并将捕获的异常指定为原因。

   try
   {
      ...
   }
   catch(Exception ex)
   {
      throw ExceptionBundle.EXCEPTIONS.calculationError(
                                       ex, "calculating payment due per day");
   }

   Copy to Clipboard Toggle word wrap

1. 如果您还没有这样做，请将您的 Maven 设置配置为使用 JBoss EAP 存储库。如需更多信息，请参阅使用 Maven 设置配置 JBoss EAP Maven 存储库。

   在项目的 pom.xml 文件的 <dependencyManagement> 部分中包含 jboss-eap-jakartaee8 BOM。

   <dependencyManagement>
     <dependencies>
       <!-- JBoss distributes a complete set of Jakarta EE APIs including
         a Bill of Materials (BOM). A BOM specifies the versions of a "stack" (or
         a collection) of artifacts. We use this here so that we always get the correct versions of artifacts.
         Here we use the jboss-javaee-7.0 stack (you can
         read this as the JBoss stack of the Jakarta EE APIs). You can actually
         use this stack with any version of JBoss EAP that implements Jakarta EE. -->
       <dependency>
         <groupId>org.jboss.bom</groupId>
          <artifactId>jboss-eap-jakartaee8</artifactId>
          <version>7.4.0.GA</version>
          <type>pom</type>
          <scope>import</scope>
       </dependency>
     <dependencies>
   <dependencyManagement>

   Copy to Clipboard Toggle word wrap

2. 将 Maven 依赖项添加到项目的 pom.xml 文件中：

   1. 添加 jboss-logging 依赖项，以访问 JBoss Logging 框架。

   2. 如果您计划使用 JBoss Logging 工具，还要添加 jboss-logging-processor 依赖项。

      这两个依赖关系都在上一步中添加的 JBoss EAP BOM 中提供，因此每个依赖项的 scope 元素可以设置为 提供 ：

      <!-- Add the JBoss Logging Tools dependencies -->
      <!-- The jboss-logging API -->
      <dependency>
         <groupId>org.jboss.logging</groupId>
         <artifactId>jboss-logging</artifactId>
         <scope>provided</scope>
      </dependency>
      <!-- Add the jboss-logging-tools processor if you are using JBoss Tools  -->
      <dependency>
         <groupId>org.jboss.logging</groupId>
         <artifactId>jboss-logging-processor</artifactId>
         <scope>provided</scope>
      </dependency>

      Copy to Clipboard Toggle word wrap

3. maven-compiler-plugin 必须至少是 3.1 版本，并且针对目标及生成的 1.8 源进行配置。

   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.1</version>
      <configuration>
         <source>1.8</source>
         <target>1.8</target>
      </configuration>
   </plugin>

   Copy to Clipboard Toggle word wrap