BIRT 2.2.2 國際化 (i18n) 完整攻略：報表檔案與 Console 介面雙軌並行

環境版本

• OS: Windows Vista Enterprise
• BIRT: birt-report-designer-all-in-one-2_2_2 (BIRT 2.2.2)
• App Server: Apache Tomcat 6.0.18 (亦適用 JBoss 等)

一、報表檔案 (.rptdesign) 國際化

1. 設定資源檔

1. 報表設計師 Layout 視圖點擊空白處 → 屬性視窗 → Resources 標籤
2. 點擊 Add，輸入基底名稱 (如 MyResources)

2. 命名規則與放置位置

• 資源檔命名：MyResources_zh.properties, MyResources_en_US.properties (符合 Java I18N Locale 格式)
• 放置路徑：在 web.xml 定義 BIRT_RESOURCE_PATH 參數指向的目錄下

<context-param>
  <param-name>BIRT_RESOURCE_PATH</param-name>
  <param-value>/WEB-INF/birt/resources</param-value>
</context-param>

3. 報表元素綁定鍵值

1. 選取文字元素 → 屬性 → Expression 選 JavaScript Expression
2. 輸入鍵值：resource["name"] (對應 properties 檔的 name=...)

4. 實測切換語系

• URL 參數 __locale=en_US → 顯示英文
• URL 參數 __locale=zh → 顯示中文

二、BIRT Viewer Console 介面國際化 (進階)

問題

Console 國際化檔內建於 viewservlets.jar!/Messages.properties，直接在 JAR 內新增語系檔 無效，且難以維護。

原始碼追蹤關鍵類

// BirtResources.getMessage()
ViewerResourceHandle handle = getResourceHandle();
return handle.getMessage(key);

// ViewerResourceHandle extends ResourceHandle
// ResourceHandle 建構子：
String bundleName = this.getClass().getName(); // 以類名為基底
bundleName = bundleName.substring(0, lastDot) + "." + BUNDLE_NAME; // "Messages"
resources = UResourceBundle.getBundleInstance(bundleName, locale, classLoader);

資源檔由 classLoader 載入，固定在 JAR 內類路徑下。

修正方案：外部化資源檔路徑

1. 修改 ReportEngineService.createGetParameterDefinitionTask() 注入 locale：

task.setLocale(ParameterAccessor.getLocale(request));

2. 重寫 ResourceHandle 建構子，從 BIRT_RESOURCE_PATH 讀取外部檔案：

public ResourceHandle(ULocale locale) {
    if (locale == null) locale = ULocale.getDefault();
    String birtResourceFolder = ParameterAccessor.processRealPath(context,
        context.getInitParameter("BIRT_RESOURCE_PATH"), null, false);
    String bundleName = birtResourceFolder + "/" + BUNDLE_NAME + "_" + locale.getLanguage() + "_" + locale.getCountry();
    try (Reader reader = new FileReader(bundleName)) {
        resources = new PropertyResourceBundle(reader);
    } catch (IOException e) { e.printStackTrace(); }
}

如此即可將 Console 國際化檔與報表資源檔統一放在 BIRT_RESOURCE_PATH 目錄下，脫離 JAR 管理。

三、常見問題快速解決

總結

• 報表檔 i18n：標準 Java ResourceBundle 機制，設定 Resources 屬性 + BIRT_RESOURCE_PATH 即可
• Console i18n：原始碼綁定 JAR 內路徑，需修改 ResourceHandle 並注入 locale 才能外部化
• 建議將修改版打包為專屬 birt-custom.jar，避免升級覆蓋