Weblate 前端

前端目前是使用 Bootstrap、jQuery 和少量第三方庫建置的。

支援的瀏覽器

Weblate 支援所有主要瀏覽器和平台的最新的、穩定的版本。

不明確支援使用最新版的 WebKit、Blink 或 Gecko的替換瀏覽器，無論是否直接還是通過平台的 web 檢視 API。然而，Weblate應該（在多數情況下）頁在這些瀏覽器中正常顯示並工作。

其它瀏覽器也能工作，但一些特性會受到限制。

無障礙功能

Weblate 的新增及變更後使用者功能會在可行範圍內以 WCAG 2.2 AA 等級為目標。新增自訂互動程式碼之前，請優先使用語意化 HTML 與 Bootstrap 元件。

變更前端時：

  • 讓所有互動式控制項都能透過鍵盤操作及使用。

  • 保持合乎邏輯的焦點順序，並保留可見的焦點樣式。

  • 請優先使用原生按鈕、連結、輸入欄位、選取方塊及表格，而非自訂小工具。

  • 視需要為每個表單控制項關聯標籤、說明文字及驗證錯誤。

  • 請勿只使用色彩、圖示形狀或位置來傳達狀態。

  • 若動態狀態變更無法透過其他方式讓輔助技術察覺，請加以提示。

  • 動畫或捲動行為應遵循減少動態效果的偏好設定。

  • 使用純鍵盤導覽測試變更後的工作流程，並在可行時以螢幕閱讀器進行抽查。

使用者介面慣例

相依套件管理

在 Django 專案的 client 中安裝及管理 第三方 程式庫可能有些棘手。本節提供逐步指南，說明如何使用 Webpack 安裝及管理 Weblate 用戶端 使用的第三方程式庫。

先決條件

安裝前，請確保您具備下列前提條件：

  • 受支援的 Node.js 版本。

  • 您的系統已安裝 yarn 套件管理程式。

  • 執行 cd client。

  • 執行 yarn install --check-files。

安裝

要安裝庫，請首先執行下列指令：

yarn add <lib-name>

匯入函式庫

接著，有兩種辦法來匯入庫：

  1. 如果它是專案層級的庫（所有/多數頁面都用到/需要）：

    • 在 src/main.js 中匯入程式庫。

    • 並視需要在全域範圍宣告。

  2. 如果它是特定頁面的庫（僅用於特定頁面或範本）：

    • 建立一個名為 src/<lib-name>.js 的檔案。

    • 在該檔案中匯入程式庫，接著將它加入 window 物件，使其可供全域存取。

    • 在 webpack.config.js 中新增條目：<lib-name>: "src/<lib-name>.js".

    • 在 webpack.config.js 的 mainLicenseTransform 中，將程式庫名稱加入 excludePrefixes 陣列。

    • 在 webpack.config.js 的 plugins 陣列中，將授權檔名加入 LicensePlugin 的 additionalFiles。

    • 為先前步驟中引入的許可檔案建立一個 <lib-name>LicenseTransform 函式並使用它。

    注意：用第三方庫的實際名稱替換 <lib-name> 。

建置函式庫

執行下列指令建置專案所用的庫：

yarn build

將庫包含進去

程式庫現已建置完成，可供使用。請依照下列步驟納入程式庫：

  1. 若程式庫是在 src/main.js 中匯入，則不需要其他步驟（因為已納入 base.html）。

  2. 若程式庫是在專用檔案 src/<lib-name>.js 中匯入，請在 weblate/templates 中使用 include 標籤，連結至建置後的靜態 JavaScript 檔案：

{% load static %}
<script src="{% static 'js/vendor/<lib-name>.js' %}"></script>

程式碼風格

Weblate 使用 Biome 格式化及檢查 JavaScript 與 CSS 程式碼。Django 範本則分別由 djade 與 djlint 格式化及檢查。

在地化

如果在前端程式碼中需要任何使用者可見的文字，那麼應該將其在地化。在多數情況下，所有需要的是將文字打包到 gettext 函式內部，但也有更復雜的特性來使用：

document.write(gettext("this is to be translated"));

var object_count = 1 // or 0, or 2, or 3, ...
s = ngettext("literal for the singular case",
        "literal for the plural case", object_count);

fmts = ngettext("There is %s object. Remaining: %s",
        "There are %s objects. Remaining: %s", 11);
s = interpolate(fmts, [11, 20]);
// s is "There are 11 objects. Remaining: 20"

也參考

Django 文件中的翻譯主題

圖標

Weblate 目前使用 Material Design Icons，如果您正在尋找新符號可以看一看。

此外，有 scripts/optimize-svg 來減小 SVG 的大小，因為多數圖示嵌入在 HTML 中，而使路徑有風格。