Pentaho技术白皮书（六）--本地化指南

这个指南将帮助你将英文版的 Pentaho BI 平台翻译成其他语言。你需要预配置的安装包和一个文本编辑器。用户接口和日志文件的所有 messages 均存放在文本文件中。这些文本文件的名字均以.properties 为后缀，位于很多文件夹中。为支持一种新的语言，你需要为你的语言创建 .properties 文件。这些文件的命名是有标准的，我们已经为几种语言创建好了文件。

 

在构造 Pentaho BI 平台时，我们一直遵循 Sun 的国际化一个 Java 应用程序的标准，这使得准备任何语言的平台仅仅是翻译的事情，而不需要修改代码。有关 Sun 的如何国际化一个Java 应用程序的国际标准，推荐阅读以下资料：   •  Internationalize Your Software, Jeff Friesen, Java World •  Java Internationalization: An Overview, John Connor, Sun Microsystems Inc. •  Java Internationalization: Localization with Resource Bundles, John Connor, Sun Microsystems Inc. •  Internationalization, O'Rielly ONJava.com, David Flanagan 这个国际化指南并没有覆盖如何翻译 samples 使用的 sample 数据的信息，以后的版本中将会提供。

 

01. 开始

This page last changed on Nov 29, 2006 by mbatchelor.

 

1.  首先访问 http://www.pentaho.org/discussion 上的 Internationalization 论坛，看看是否有其他人已经开始进行你的语言上的翻译了。

2.  如果你想翻译成法语，德语，西班牙语，意大利语，葡萄牙语或中文，我们已经为你创建好了.properties 文件。如果你想翻译成其他语言，发送 email 到communityconnection@pentaho.org或在 Pentaho 论坛上发帖。

3.  从 SourceForge 下载名为 pentaho_demo-x.x.x.x.zip 的最新版本的预配置安装包。确保你知道如何运行 demo 网页，portal 页面和 samples。帮助信息请查看Getting Started Guide 和论坛。

4.  在预配置安装包和 pentaho-solutions 目录中寻找后缀为 .properties 的文件，你会看到如下类似信息：

•  *.properties (英语)

•  *_fr.properties (法语)

•  *_de.properties (德语)

•  *_it.properties (意大利语)

•  *_es.properties (西班牙语)

•  *_pt.properties (葡萄牙语)

•  *_cn.properties (中文)

 

如果你的语言不在列表中，或你想创建某种语言的特定版本，例如 French Canadian，请联系 communityconnection@pentaho.org，我们将提供相应帮助。标准语言和国家代码的列表请参考以下网页：

 

•  语言代码： http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt

•  国家代码： http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html

 

 

02. 一般概念

This page last changed on Nov 29, 2006 by mbatchelor.

 

向用户显示的所有文本信息均存储在 .properties 文件中。每当平台需要一块文本，就加载适当的 .properties 文件，从中读取必需的文本。对于系统支持的每种语言，都有 .properties 文件。两个字符的语言代码和两个字符的国家代码（可选）附加在基本的文件名上，以标识文件所支持的语言。例如：

 

messages.properties: messages 文件的默认英语版本

messages_fr.properties: messages 文件的法语版本

messages_de.properties: messages 文件的德语版本

messages_fr_CA.properties: messages 文件的 French Canadian 版本

 

当用户发出一个请求后，平台探测那个用户的国家和语言，并定位文件的正确语言版本。在运行时读取 .properties 文件，并不编译进平台。这使得执行翻译和查看结果是一个很简单的过程。

 

03. 翻译 Samples

This page last changed on Nov 29, 2006 by mbatchelor.

 

开始翻译平台的最轻松的方式是翻译 samples。预配置安装包的 pentaho-solutions 目录包含运行 sample solutions 的所有必需文件。用户可以看见 .properties 文件中的所有文本，他们均该被翻译。这些文件的根目录是：

 

<pentaho-demo>/pentaho-solutions/

 

pentaho-solutions 下的每个目录包含一个 index.xml 文件和一个相应的 index.properties 文件。例如，当一个英语用户请求 pentaho-solutions/samples 目录下的 index.xml 文件时，平台会在此目录下寻找 index.properties 文件。当一个法语用户登录后，平台会寻找 index_fr.properties。对于一个德语用户，它会寻找 index_de.properties。如果找不到 index_[country-code].properties 文件，使用默认的 index.properties 文件。如果你是一个德语翻译人员，你需要创建一个名为 index_de.properties 的新文件，添加德语版本的被翻译文本，并刷新你的浏览器，这样将会为德语用户显示德语信息。为了选择正确的文本，在 base document 和 .properties 文件中的文本之间有一个mapping scheme。对于实例 index.xml，以下是此文件中的文本：

^{<?xml version='1.0' encoding='ISO-8859-1'?>}

^<index>

^{<name>%name</name>}

^{<description>%description</description>}

^{<icon>solutions.png</icon>}

^{<visible>true</visible>}

^</index>

以下是 index.properties 文件中的内容：

name=Pentaho BI Components Demo description=These sample JSP pages show ...

 

为翻译 XML 文件，我们使用 Eclipse 标准的 mapping XML 文本，其在 .properties 文件中每个名字前使用一个 % 标记。在这个实例中，XML 文件中的 %name 将被 .properties 文件中的 name=key 后的文本所替换。samples navigation JSP 使用 index.xml 文件产生一套 solutions 所使用的 names，descriptions 和 image。以下是 index_fr.properties 文件中的内容：

 

name=Démo De Composants de BI De Pentaho description=Ces pages témoin JSP montrent comment ...

 

注意：这个实例法语翻译是由一个翻译程序生成的，不要太较真。翻译 samples 的步骤如下：

 

1.  从 samples 目录开始

2.  打开用于你的语言的每个 .properties 文件。

3.  编辑等号‘=’右边的英语文本，使用你的语言中的正确文本替换它。重要：不要改变等号‘=’左边的文本。例如：name=Démo De Composants

 

查看你的 samples 翻译结果

 

在你翻译每个文件，或每一行时，你可以查看结果。仅仅通过刷新你的浏览器，一些文本就会发生改变。Action documents 的 names 和 descriptions 被缓存，并必须被发布。为了发布，浏览到Pentaho Preconfigured Install Demo 的顶层。默认 URL 是 http://localhost:8080/pentaho。在 Refresh 区域，点击 "Solution Repository."，加载一个弹出式对话框。从列表中，为“Solution Repository” publisher 点击 “Publish” 链接。在翻译时，保证这个页面可访问是很有用的。

 

在翻译 samples 时会遇到 3 种文件类型。在翻译完他们的 .properties 文件后，可以如下验证我们的修改：

 

1.  index.xml-- 用于在 samples 的组之间进行浏览。你可以浏览至那个组，查看 index.properties 文件的修改结果。Getting Started 就是一个这样的组。

2.  *.url--定义和 samples 一起显示，用于发起 actions 的 URLs。admin 文件夹下的 SchedulerAdmin 就是一个实例。

3.  *.xaction. 实现 BI solutions 的 Action documents。选择验证你的语言修改的 action。

 

当你准备共享你的工作时，你可以将之发送至 Pentaho，以包含在平台中。

 

04. 翻译 Pentaho Application

This page last changed on Nov 29, 2006 by mbatchelor.

 

Pentaho application 目录树中的 .properties 文件包含 application 文件中所使用的文本。这些包含在错误消息，调试信息和用户接口文本。这些文件均命名为 messages.properties。在预配置安装中，application resource 包位于 WEB-INF 目录下。默认的，WEB-INF 目录的路径如下：/pentaho-demo/jboss/server/default/deploy/pentaho.war/WEB-INF

 

通常，这些文件中的所有文本对于用户并不均是可见的。为了更清楚些，我们在 .properties 文件中对每个文本块均使用了一个命名约定。

 

前缀	意义
.USER_	这段文本对用户可见。
.ERROR_	这段文本表示系统中的一个错误。如果 log level 是ERROR 或更高，则在 event logs 中可见。
.WARN_	这段文本表示系统中的一个警告。如果 log level 是WARN 或更高，则在 event logs 中可见。
.INFO_	这段文本表示系统中的一个错误。如果 log level 是INFO 或更高，则在 event logs 中可见。
.DEBUG_	这段文本表示用于问题跟踪的详细系统信息。如果 log level 是 DEBUG 或更高，则在 event logs 中可见。

 

你翻译 messages 的优先级顺序如下：

1.  WEB-INF\portlet.properties 文件中的所有文本

2.  根据以下表进行翻译：

 

对于以下路径	翻译带有以下前缀的文本名
WEB-INF\classes\org\pentaho\locale WEB-INF\classes\org\pentaho\ui\component	. USER_ .ERROR_ .WARN_ .DEBUG_
WEB-INF\classes\org\pentaho\ui\portlet	.USER_ .ERROR_ .WARN_ .DEBUG_
WEB-INF\classes\org\pentaho\ui\component\charting	. USER_ .ERROR_ .WARN_ .DEBUG_
WEB-INF\classes\org\pentaho\ui\portlet\charting	.USER_ .ERROR_ .WARN_ .DEBUG_
WEB-INF\classes\org\pentaho\ui\servlet	.USER_ .ERROR_ .WARN_ .DEBUG_

 

如果你仅想翻译预配置安装包和 samples，你仅仅需要翻译 <pentaho-demo>/jboss/server/default/deploy/pentaho.war/WEB-INF 下的以下文件：

 

\portlet.properties

\classes\org\pentaho\locale\messages.properties

 

这和 Pentaho 预配置安装之前的发布版本很不同。之前每个 Java 包拥有自己的 ResourceBundle 管理器 Messages.java 以及一套名为 messages.properties (每种语言一个)的属性文件。现在我们已经使用一套 manager 类，org\pentaho\messages，将我们的所有资源集成进上列的目录中。每种语言都有一个 messages.properties 文件，我们已经将之前翻译的所有包合并进一个本地语言特定的副本中。这应该更容易定位要翻译的字符串，因为他们均位于相同的位置。

 

如同 samples，.properties 文件的格式是 name=message。你必须小心不要修改等号 ‘=’ 左边的任何东西。所有的 messages 必须在一行上。不要在 .properties 文件中添加回车键。

 

在 application messages 中，有特殊的可替换型参数标记，如 {0} 和 {1} 等。他们用于构建 messages，例如：

HelloWorld.USER_HELLO_WORLD_TEXT=\nHello World. {0}\n

 

{0} 表示一个占位符，不应该被改变。这些占位符的文本来自于数据，由 application 插入。原文的所有占位符必须出现在被翻译的字符串中。占位符的测试位置和他们出现的顺序可以被修改，以匹配你的语言的语法。因此，我们的第二个实例可能如下所示：  

 

HelloWorld.USER_HELLO_WORLD_TEXT =\nBonjour Monde.{0}\n

 

查看你的 application 翻译结果

 

为查看你的修改，你必须重启应用服务器。使用 stop-pentaho 和 start-pentaho 来完成。文本的名字可以帮助断定从哪里寻找你的结果。在这个实例中，当执行 Hello World 组件时，你能看到显示给用户的一个 message。

 

 

从你的浏览器测试

 

如果你想在你的 web 浏览器所使用的语言间进行切换，你可以改变你的 web 浏览器的语言首选项。

 

在 Internet Explorer 中改变语言首选项

在 Internet Explorer 中，按照以下步骤改变你的语言首选项：

1. 从主菜单，浏览至工具菜单，然后选择 Internet 选项…

2. 在常规标签页，点击语言… 按钮。

3. 在语言对话框，点击添加… 按钮。

4. 你将打开一个对话框，从中你可以选择你需要的语言。选择你想首选使用的语言，然后点击 OK。

5. 现在你选择的语言应该出现在语言对话框。选择你刚才添加的语言，点击上移按钮，直到它出现在列表的顶部。

6. 点击 OK 直到关闭了所有的对话框。

7. 刷新你的网页。

 

 

在 Firefox 中改变语言首选项

在 Mozilla Firefox 中，按照以下步骤改变你的语言首选项：

1. 从主菜单，浏览至 Tools 菜单，然后选择 Options…

2. 在 Advanced 标签页，点击 Edit Languages… 按钮。

3. 在 Languages 对话框，选择对话框底部的复选框。

4. 你将打开一个可用语言的列表，选择你想使用的语言。

5. 点击 Add 按钮将你选择的语言添加进显示列表中。

6. 现在你的选择应该出现在 Edit Languages 对话框中的列表中。在列表中选择你刚添加的语言，然后点击上移按钮，直到它出现在列表的顶部。

7. 点击 OK 直到关闭所有对话框。

8. 刷新你的网页

 

05. 翻译 Pentaho 报表设计指南

This page last changed on Nov 29, 2006 by mbatchelor.

 

报表设计指南自带一个单独的 messages.properties 文件，其包含所有的 base resource strings。如果你想翻译报表设计指南，你必须找到 RDW/lib 目录下的 pentaho-reporting-X.X.X.jar 文件。使用一个 unzip 工具将这个 jar 解压到RDW/resources，也就是在 RDW/resources 下创建一个 "org" 文件夹。现在你可删除原来的 jar 文件(从 classpath 删除它)。

 

浏览到 org/pentaho/jfreereport/messages (在 "lib" 下)。按照之前描述的命名规范，为你的语言创建一个 .properties 文件。因此如果你使用德语，创建一个 messages_de.properties 文件。对于你想翻译的每种资源，从原先的 messages.properties 文件中将键值（key）复制到你正在翻译的文件中，翻译右边的值。

 

你可在这种模式下持续测试，不必重新打包传回 Pentaho。当你对翻译结果满意的时候，仅仅将你的messages_XX.properties 文件提交给我们即可。

 

06. 翻译 Design Studio

This page last changed on Nov 29, 2006 by mbatchelor.

 

Pentaho Design Studio 自带一个单独的 messages.properties 文件，其包含所有的 base resource 字符串。如果你想翻译 Design Studio，你必须到你的 Design Studio (Eclipse) 安装目录下的plugins\org.pentaho.workbench.editors.actionsequence_x.x.x.x 目录找到 pentaho-action-editor.jar 文件。使用一个 unzip 工具将这个 jar 解压到一个工作目录下。

 

浏览到 org/pentaho/workbench/messages。根据“一般概念”一节所描述的命名规范，为你的语言创建一个 .properties 文件。因此如果你使用德语，就创建一个 messages_de.properties 文件。对于你想翻译的每种资源，从原先的 messages.properties 文件中将键值（key）复制到你正在翻译的文件中，翻译右边的值。

 

Zip 你的工作目录的内容，命名为 pentaho-action-editor.jar，将这个新的 jar 文件复制回 plug-in 目录。

 

07. Unicode 支持

This page last changed on Nov 29, 2006 by mbatchelor.

 

Pentaho BI 平台支持 Unicode，成功完成翻译请按照以下指南。

 

 

Properties 文件

这些文件作为 ISO-8859-1 编码的文件读取。为在这些文件中存储 Unicode 字符，它们必须使用 Java, \uNNNN 或 XML, NNNN; 编码，编码和存储为 ASCII 文件。你可以使用一个文本编辑器，例如SC Unipad (http://www.unipad.org) 来编辑 Pentaho.properties 文件，并用正确的格式保存它们。

 

XML 文件

这些文件中的所有 Unicode 字符必须使用 XML, NNNN; 编码存储。

 

 

XSL 文件

XSLs 文件中的 Unicode 字符必须使用 XML NNNN; 编码存储。XSLs 中使用的，存储在 org/Pentaho/ui/messages.properties 文件中的 messages 的 Unicode 字符应该使用 msg:getXslString 访问，且应该关闭输出 escaping。

^{<xsl:value-of}

^{select="msg:getXslString('UI.USER_FILTER_PANEL_HINT')"}

^{disable-output-escaping="yes"}

^/>

 

JFreeReport 定义

JFreeReport 的报表定义中的 Unicode 字符应该使用 XML, NNNN; 编码存储。而且，报表配置区域应该指定 PDF 输出所使用的 Identity-H 编码和嵌入式字体。例如：

^{<configuration>}

^<property

^{name="org.jfree.report.modules.output.pageable.pdf.Encoding">Identity-H</property>}

^{<property name="org.jfree.report.modules.output.pageable.pdf.EmbedFonts">true</property>}

^{</configuration>}

你需要使用支持 Unicode 字符的字体，例如‘Ariel Unicode MS’。

 

08. 提交你的翻译

This page last changed on Mar 13, 2007 by phart.

 

如果你想提交任何文件，请发邮件至：communityconnection@pentaho.org。你将需要签署一份 Contributor Agreement (http://www.pentaho.org/contributor_agreement )，然后我们将告知你如何提交。