Merge pull request #1195 from picc-lu/picc-lu-patch-1

harawata · web-flow · commit a4da2b02cca9 · 2018-02-27T01:41:39.000+09:00
Correct Chinese translation in logging.xml
diff --git a/src/site/zh/xdoc/logging.xml b/src/site/zh/xdoc/logging.xml
@@ -26,10 +26,9 @@
   </properties>
 
   <body>
-    <section name="Logging">
+    <section name="日志">
       <p></p>
-      <p>
-        Mybatis内置的日志工厂提供日志功能，具体的日志实现有以下几种工具：
+      <p>Mybatis 的内置日志工厂提供日志功能，内置日志工厂将日志交给以下其中一种工具作代理：
       </p>
       <ul>
         <li>
@@ -48,18 +47,8 @@
           JDK logging
         </li>
       </ul>
-      <p>
-        具体选择哪个日志实现工具由MyBatis的内置日志工厂确定。它会使用最先找到的（按上文列举的顺序查找）。
-        如果一个都未找到，日志功能就会被禁用。
-      </p>
-      <p>
-        不少应用服务器的classpath中已经包含Commons Logging，如Tomcat和WebShpere，
-        所以MyBatis会把它作为具体的日志实现。记住这点非常重要。这将意味着，在诸如
-       WebSphere的环境中——WebSphere提供了Commons Logging的私有实现，你的Log4J配置将被忽略。
-       	这种做法不免让人悲催，MyBatis怎么能忽略你的配置呢？事实上，因Commons Logging已经存
-       	在了，按照优先级顺序，Log4J自然就被忽略了！不过，如果你的应用部署在一个包含Commons Logging的环境，
-       	而你又想用其他的日志框架，你可以通过在MyBatis的配置文件mybatis-config.xml里面添加一项setting（配置）来选择一个不同的日志实现。
-      </p>
+      <p>MyBatis 内置日志工厂基于运行时自省机制选择合适的日志工具。它会使用第一个查找得到的工具（按上文列举的顺序查找）。如果一个都未找到，日志功能就会被禁用。</p>
+      <p>不少应用服务器（如 Tomcat 和 WebShpere）的类路径中已经包含 Commons Logging，所以在这种配置环境下的 MyBatis 会把它作为日志工具，记住这点非常重要。这将意味着，在诸如 WebSphere 的环境中，它提供了 Commons Logging 的私有实现，你的 Log4J 配置将被忽略。MyBatis 将你的 Log4J 配置忽略掉是相当令人郁闷的（事实上，正是因为在这种配置环境下，MyBatis 才会选择使用 Commons Logging 而不是 Log4J）。如果你的应用部署在一个类路径已经包含 Commons Logging 的环境中，而你又想使用其它日志工具，你可以通过在 MyBatis 配置文件 mybatis-config.xml 里面添加一项 setting 来选择别的日志工具。</p>
       <source><![CDATA[<configuration>
   <settings>
     ...
@@ -68,27 +57,18 @@
   </settings>
 </configuration>]]>
       </source>
-      <p>
-      	logImpl可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING
-      	或者是实现了接口<code>org.apache.ibatis.logging.Log</code>的类的完全限定类名，
-      	并且这个类的构造函数需要是以一个字符串（String类型）为参数的。
-      	（可以参考org.apache.ibatis.logging.slf4j.Slf4jImpl.java的实现）
+      <p>logImpl 可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了接口 <code>org.apache.ibatis.logging.Log</code> 的，且构造方法是以字符串为参数的类的完全限定名。（译者注：可以参考org.apache.ibatis.logging.slf4j.Slf4jImpl.java的实现）
       </p>
-      <p>
-      	你根据需要调用如下的某一方法：
+      <p>你也可以调用如下任一方法来使用日志工具：
       </p>
       <source><![CDATA[org.apache.ibatis.logging.LogFactory.useSlf4jLogging();
 org.apache.ibatis.logging.LogFactory.useLog4JLogging();
 org.apache.ibatis.logging.LogFactory.useJdkLogging();
 org.apache.ibatis.logging.LogFactory.useCommonsLogging();
 org.apache.ibatis.logging.LogFactory.useStdOutLogging();]]></source>
-      <p>如果的确需要调用以上的某个方法，请在其他所有MyBatis方法之前调用它。另外，只有在相应日志实现中存在
-        的前提下，调用对应的方法才是有意义的，否则MyBatis一概忽略。如你环境中并不存在Log4J，你却调用了
-        相应的方法，MyBatis就会忽略这一调用，代之默认的查找顺序查找日志实现。
-      </p>
-      <p>关于SLF4J、Apache Commons Logging、Apache Log4J和JDK Logging的API介绍已经超出本文档的范围。
-        不过，下面的例子可以作为一个快速入门。关于这些日志框架的更多信息，可以参考以下链接：
+      <p>如果你决定要调用以上某个方法，请在调用其它 MyBatis 方法之前调用它。另外，仅当运行时类路径中存在该日志工具时，调用与该日志工具对应的方法才会生效，否则 MyBatis 一概忽略。如你环境中并不存在 Log4J，你却调用了相应的方法，MyBatis 就会忽略这一调用，转而以默认的查找顺序查找日志工具。
       </p>
+      <p>关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介绍不在本文档介绍范围内。不过，下面的例子可以作为一个快速入门。关于这些日志框架的更多信息，可以参考以下链接：</p>
       <ul>
         <li>
           <a href="http://commons.apache.org/logging">Apache Commons Logging</a>
@@ -100,35 +80,31 @@ org.apache.ibatis.logging.LogFactory.useStdOutLogging();]]></source>
           <a href="http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/">JDK Logging API</a>
         </li>
       </ul>
-      <subsection name="Logging Configuration">
-        <p>MyBatis可以对包、类、命名空间和全限定的语句记录日志。
+      <subsection name="日志配置">
+        <p>你可以对包、映射类的全限定名、命名空间或全限定语句名开启日志功能来查看 MyBatis 的日志语句。
         </p>
-        <p>具体怎么做，视使用的日志框架而定，这里以Log4J为例。配置日志功能非常简单：添加几个配置文件，
-            如log4j.properties,再添加个jar包，如log4j.jar。下面是具体的例子，共两个步骤：
+        <p>再次说明下，具体怎么做，由使用的日志工具决定，这里以 Log4J 为例。配置日志功能非常简单：添加一个或多个配置文件（如 log4j.properties），有时需要添加 jar 包（如 log4j.jar）。下面的例子将使用 Log4J 来配置完整的日志服务，共两个步骤：
         </p>
         <p></p>
         <h4>
-          步骤1： 添加 Log4J 的 jar 包
+          步骤 1：添加 Log4J 的 jar 包
         </h4>
-        <p>因为采用Log4J，要确保在应用中对应的jar包是可用的。要满足这一点，只要将jar包添加到应用的classpath中即可。
-         Log4J的jar包可以从上面的链接中下载。
+        <p>因为我们使用的是 Log4J，就要确保它的 jar 包在应用中是可用的。要启用 Log4J，只要将 jar 包添加到应用的类路径中即可。Log4J 的 jar 包可以在上面的链接中下载。
         </p>
-        <p>具体而言，对于web或企业应用，需要将<code>log4j.jar</code> 添加到<code>WEB-INF/lib</code> 目录； 对于独立应用，
-            可以将它添加到jvm的 <code>-classpath</code>启动参数中。
+        <p>对于 web 应用或企业级应用，则需要将 <code>log4j.jar</code> 添加到 <code>WEB-INF/lib</code> 目录下；对于独立应用，可以将它添加到JVM 的 <code>-classpath</code> 启动参数中。
         </p>
         <p></p>
         <h4>
-          步骤2：配置Log4J
+          步骤 2：配置 Log4J
         </h4>
-        <p>配置Log4J比较简单， 比如需要记录这个mapper接口的日志:
-        </p>
+        <p>配置 Log4J 比较简单，假如你需要记录这个映射器接口的日志：
+        </p>
         <source><![CDATA[package org.mybatis.example;
 public interface BlogMapper {
   @Select("SELECT * FROM blog WHERE id = #{id}")
   Blog selectBlog(int id);
 }]]></source>
-        <p>只要在应用的classpath中创建一个名称为<code>log4j.properties</code>的文件，
-            文件的具体内容如下：
+        <p>在应用的类路径中创建一个名称为 <code>log4j.properties</code> 的文件，文件的具体内容如下：
         </p>
         <source><![CDATA[# Global logging configuration
 log4j.rootLogger=ERROR, stdout
@@ -138,28 +114,22 @@ log4j.logger.org.mybatis.example.BlogMapper=TRACE
 log4j.appender.stdout=org.apache.log4j.ConsoleAppender
 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
 log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n]]></source>
-        <p>添加以上配置后，Log4J就会把
-          <code>org.mybatis.example.BlogMapper</code>
-          的详细执行日志记录下来，对于应用中的其它类则仅仅记录错误信息。
-        </p>
-        <p>也可以将日志从整个mapper接口级别调整到到语句级别，从而实现更细粒度的控制。如下配置只记录
-          <code>selectBlog</code> 语句的日志：
+        <p>添加以上配置后，Log4J 就会记录 <code>org.mybatis.example.BlogMapper</code> 的详细执行操作，且仅记录应用中其它类的错误信息（若有）。</p>
+        <p>你也可以将日志的记录方式从接口级别切换到语句级别，从而实现更细粒度的控制。如下配置只对 <code>selectBlog</code> 语句记录日志：
         </p>
 
         <source>log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source>
         
-        <p>与此相对，可以对一组mapper接口记录日志，只要对mapper接口所在的包开启日志功能即可：</p>
+        <p>与此相对，可以对一组映射器接口记录日志，只要对映射器接口所在的包开启日志功能即可：</p>
 
         <source>log4j.logger.org.mybatis.example=TRACE</source>
         
-        <p>某些查询可能会返回大量的数据，只想记录其执行的SQL语句该怎么办？为此，Mybatis中SQL语
-             句的日志级别被设为DEBUG（JDK Logging中为FINE），结果日志的级别为TRACE（JDK 
-           Logging中为FINER)。所以，只要将日志级别调整为DEBUG即可达到目的：
+        <p>某些查询可能会返回庞大的结果集，此时只想记录其执行的 SQL 语句而不想记录结果该怎么办？为此，Mybatis 中 SQL 语句的日志级别被设为DEBUG（JDK 日志设为 FINE），结果的日志级别为 TRACE（JDK 日志设为 FINER)。所以，只要将日志级别调整为 DEBUG 即可达到目的：
         </p>
 
         <source>log4j.logger.org.mybatis.example=DEBUG</source>
         
-        <p>要记录日志的是类似下面的mapper文件而不是mapper接口又该怎么呢？
+        <p>要记录日志的是类似下面的映射器文件而不是映射器接口又该怎么做呢？
         </p>
 
       <source><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>
@@ -172,23 +142,23 @@ log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n]]></source>
   </select>
 </mapper>]]></source>
 
-		<p>对这个文件记录日志，只要对命名空间增加日志记录功能即可：
+		<p>如需对 XML 文件记录日志，只要对命名空间增加日志记录功能即可：
 		</p>
 
         <source>log4j.logger.org.mybatis.example.BlogMapper=TRACE</source>
 
-		<p>	进一步，要记录具体语句的日志可以这样做：
-		</p>
+		<p>要记录具体语句的日志可以这样做：</p>
 
         <source>log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source>
 
-		<p>看到了吧，两种配置没差别！
+		<p>你应该注意到了，为映射器接口和 XML 文件添加日志功能的语句毫无差别。
 		</p>
+		  
+		<p><span class="label important">注意</span> 如果你使用的是 SLF4J 或 Log4j 2，MyBatis 将以 MYBATIS 这个值进行调用。</p>
 
-        <p>配置文件<code>log4j.properties</code>的余下内容是针对日志格式的，这一内容已经超出本
-            文档范围。关于Log4J的更多内容，可以参考Log4J的网站。不过，可以简单试一下看看，不同的配置
-            会产生什么不一样的效果。
+        <p>配置文件 <code>log4j.properties</code> 的余下内容是针对日志输出源的，这一内容已经超出本文档范围。关于 Log4J 的更多内容，可以参考Log4J 的网站。不过，你也可以简单地做做实验，看看不同的配置会产生怎样的效果。
         </p>
+		  
       </subsection>
     </section>
   </body>
