轉-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 )，而後咱們將告知你如何提交。