# 定制 Weblate

使用 Django 和 Python 进行扩展和定制。将你的更改贡献给上游，让每个人都能受益。这降低了您的维护成本；当改变内部接口或重构代码时，Weblate 的代码会被照顾到。

#### HINT
你也可以在 [外观自定义](https://docs.weblate.org/zh-cn/latest/admin/admin.md#manage-appearance) 中定制 Weblate 外观。

#### WARNING
内部接口与模板都不被认为是稳定的 API。请每次升级都检查你的定制，接口或其语义可能未经通知就进行更改。

#### SEE ALSO
[为 Weblate 作贡献](https://docs.weblate.org/zh-cn/latest/contributing/index.md#contributing)

<a id="custom-module"></a>

## 建立 Python 模块

如果不熟悉 Python，你可以查看 [适合初学者的 Python（英文）](https://www.python.org/about/gettingstarted/)，它解释了其基本内容并指向了高级教程。

要写入有定制 Python 代码（被称为模块）的文件，需要一个地方存储它，或者在系统路径（通常像 `/usr/lib/python3.12/site-packages/` 的地方），或者在 Weblate 目录下，同样也添加到解释程序搜索路径下。

#### HINT
[使用 Docker](https://docs.weblate.org/zh-cn/latest/admin/install/docker.md#docker-deploy) 时，你可将 Python 模块置于 `/app/data/python/` (见 [Docker 容器卷](https://docs.weblate.org/zh-cn/latest/admin/install/docker.md#docker-volume)) 以便它们可以由 Weblate 从 [设置覆盖文件](https://docs.weblate.org/zh-cn/latest/admin/install/docker.md#docker-settings-override) 等处进行加载。

更好地是，将你的定制化转变为适当的 Python 包：

1. 为你的包建立文件夹（我们会使用 weblate_customization）。
2. 在里面新建 `pyproject.toml` 文件来描述包：
   ```toml
   [build-system]
   requires = ["uv_build>=0.8.18,<0.9.0"]
   build-backend = "uv_build"

   [project]
   name = "weblate-customization"
   version = "0.1.0"
   description = "Add your description here"
   requires-python = ">=3.13"
   dependencies = []
   ```
3. 为 Python 模块建立文件夹：`src/weblate_customization`
4. 在里面建立 `__init__.py` 文件来确认 Python 可以导入模块。
5. 现在可以使用 **uv pip install -e** 安装这个包。可以在 [Editable packages documentation](https://docs.astral.sh/uv/pip/packages/#editable-packages) 中找到更多信息。
6. 模块一旦安装，就可以用在 Weblate 配置中（例如 `weblate_customization.checks.FooCheck`）。

你的包结构应该看起来像这样：

```text
weblate_customization
├── pyproject.toml
└── src
    └── weblate_customization
        ├── __init__.py
        ├── addons.py
        └── checks.py
```

可以在 <[https://github.com/WeblateOrg/customize-example](https://github.com/WeblateOrg/customize-example)> 找到定制 Weblate 的示例，它涵盖了下面描述的所有题目。

## 更改标志

1. 建立简单的 Django app 来包含想要覆盖的静态文件（请参见 [建立 Python 模块](#custom-module)）。

   品牌出现在后面的文件中：

   `icons/weblate.svg`
   : 导航栏中显示的标志。

   `logo-*.png`
   : 网页图标取决于屏幕分辨率和浏览器。

   `favicon.ico`
   : 传统浏览器使用的网页图标。

   `weblate-*.png`
   : 机器人或匿名用户使用的头像。一些浏览器将这些图标用作快捷方式图标。

   `email-logo.png`
   : 在通知电子邮件中使用。
2. 把它添加到 [`INSTALLED_APPS`](https://docs.djangoproject.com/zh-hans/stable/ref/settings/#std-setting-INSTALLED_APPS)：
   ```python
   INSTALLED_APPS = (
       # Add your customization as first
       "weblate_customization",
       # Weblate apps are here…
   )
   ```
3. 运行 `weblate collectstatic --noinput`，来收集提供给客户端的静态文件。

#### SEE ALSO
* [如何管理静态文件（如图片、JavaScript、CSS）](https://docs.djangoproject.com/zh-hans/stable/howto/static-files/)
* [为静态文件提供服务](https://docs.weblate.org/zh-cn/latest/admin/install.md#static-files)

<a id="custom-addon-modules"></a>

<a id="custom-check-modules"></a>

<a id="custom-modules"></a>

## 定制的质量检查、附加组件、自动建议和自动修复

要在 Weblate 中安装你的 [定制的自动修正](https://docs.weblate.org/zh-cn/latest/admin/checks.md#custom-autofix)，[编写自己的检查](https://docs.weblate.org/zh-cn/latest/admin/checks.md#own-checks)、[定制化的机器翻译](https://docs.weblate.org/zh-cn/latest/admin/machine.md#custom-machinery) 或 [编写附加组件](https://docs.weblate.org/zh-cn/latest/admin/addons.md#own-addon) 代码：

1. 将文件放进包含 Weblate 定制的 Python 模块中（见 [建立 Python 模块](#custom-module) 或 [自定义代码](https://docs.weblate.org/zh-cn/latest/admin/install/docker.md#docker-python-override)）。
2. 在专用设置中将其完全合格的路径添加到 Python 类中：
   * [`WEBLATE_ADDONS`](https://docs.weblate.org/zh-cn/latest/admin/config.md#std-setting-WEBLATE_ADDONS)
   * [`CHECK_LIST`](https://docs.weblate.org/zh-cn/latest/admin/config.md#std-setting-CHECK_LIST)
   * [`WEBLATE_MACHINERY`](https://docs.weblate.org/zh-cn/latest/admin/config.md#std-setting-WEBLATE_MACHINERY)
   * [`AUTOFIX_LIST`](https://docs.weblate.org/zh-cn/latest/admin/config.md#std-setting-AUTOFIX_LIST)

```python
# Checks
CHECK_LIST += ("weblate_customization.checks.FooCheck",)

# Autofixes
AUTOFIX_LIST += ("weblate_customization.autofix.FooFixer",)

# Add-ons
WEBLATE_ADDONS += ("weblate_customization.addons.ExamplePreAddon",)

# Automatic suggestions
WEBLATE_MACHINERY += ("weblate_customization.machinery.SampleTranslation",)
```

#### SEE ALSO
* [定制的自动修正](https://docs.weblate.org/zh-cn/latest/admin/checks.md#custom-autofix)
* [编写自己的检查](https://docs.weblate.org/zh-cn/latest/admin/checks.md#own-checks)
* [编写附加组件](https://docs.weblate.org/zh-cn/latest/admin/addons.md#own-addon)
* [从附加组件执行脚本](https://docs.weblate.org/zh-cn/latest/admin/addons.md#addon-script)