Weblate 前端

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

支持的浏览器

Weblate 支持所有主流浏览器和平台最新的稳定版。

不明确支持使用最新版 WebKit、Blink 或 Gecko 内核的替代浏览器，无论是直接使用还是通过平台的 web view API。但是，Weblate 应该（在大多数情况下）能在这些浏览器中正常显示和运行。

其他浏览器也能工作，但一些特性会受到限制。

Accessibility

Weblate targets WCAG 2.2 Level AA for new and changed user-facing functionality where practical. Use semantic HTML and Bootstrap components before adding custom interaction code.

更改前端时：

  • Make all interactive controls reachable and usable with a keyboard.

  • Keep focus order logical and preserve visible focus styling.

  • Prefer native buttons, links, inputs, selects, and tables over custom widgets.

  • Associate every form control with a label, help text, and validation errors where applicable.

  • Do not use color, icon shape, or position as the only way to convey state.

  • Announce dynamic status changes that are not otherwise visible to assistive technology.

  • Respect reduced-motion preferences for animation or scrolling behavior.

  • Test changed workflows with keyboard-only navigation and, when practical, a screen reader spot check.

依赖项管理

在 Django 项目中安装并管理 第三方 库可能有点难处理。此部分提供了有关如何使用 Webpack 来安装并管理 Weblate 的 客户侧 所用的第三方库的逐一步骤指南。

前提

安装前，请确保你具备下列前提条件：

  • A supported Node.js release.

  • 你系统上已安装 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，请使用包含标签来链接到构建的静态 JavaScript 文件：

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

代码风格

Weblate 依赖 Biome 更改 JavaScript and CSS 代码格式并进行 lint 操作。Django 模板由 djade 处理格式，由 djlint 进行 lint 操作。

本地化

如果在前端代码中需要任何用户可见的文本，那么应该将其本地化。在多数情况下，所有需要的是将文本打包到 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 中，而使路径有风格。