Клиент Weblate

Установка

The Weblate Client is shipped separately and includes the Python module. To use the commands below, you need to install wlc using pip:

pip install wlc

Вы также можете выполнить его напрямую с помощью uvx:

uvx wlc --help

Подсказка

Вы также можете использовать этот wlc как модуль Python, см. wlc.

Использование Docker

Клиент Weblate также доступен в виде образа Docker.

Этот образ публикуется на Docker Hub: https://hub.docker.com/r/weblate/wlc

Установка:

docker pull weblate/wlc

The Docker container uses Weblate Client defaults and connects to the API deployed on localhost. Configure the API URL and API key using the normal wlc arguments or environment variables, for example --url, --key, WLC_URL, and WLC_KEY. API keys are rejected over non-local http:// URLs by default; use HTTPS, loopback HTTP for local development, or explicitly opt in to insecure HTTP.

У команды запуска контейнера следующий синтаксис:

docker run --rm weblate/wlc [WLC_ARGS]

Пример:

docker run --rm weblate/wlc --url https://hosted.weblate.org/api/ list-projects

Возможно, вы захотите передать ваш Файлы настроек в контейнер Docker. Если ваш репозиторий содержит конфигурацию проекта, например .weblate, самый простой подход — добавить вашу текущую директорию как том /home/weblate:

docker run --volume $PWD:/home/weblate --rm weblate/wlc show

When the mounted repository provides the API URL in project configuration and you pass an unscoped API key to the container, also pin the URL explicitly: WLC_KEY requires WLC_URL, and --key requires --url.

If the configured API URL uses non-local http:// and an API key is provided, the container refuses to send the key unless insecure HTTP is explicitly enabled. Prefer HTTPS; for legacy deployments, pass --allow-insecure-http or set WLC_ALLOW_INSECURE_HTTP.

Начало работы

Самый простой способ начать — создать персональную конфигурацию wlc в ~/.config/weblate (полные правила обнаружения и другие расположения см. в Файлы настроек):

[weblate]
url = https://hosted.weblate.org/api/

[keys]
https://hosted.weblate.org/api/ = APIKEY

После этого вы сможете вызывать команды на умолчательном сервере:

wlc ls
wlc commit sandbox/hello-world

См. также

Файлы настроек

Устаревшая конфигурация

Изменено в версии 1.17: Устаревшая конфигурация с использованием key без области действия больше не поддерживается.

Миграция устаревшей конфигурации:

[weblate]
url = https://hosted.weblate.org/api/
key = YOUR_KEY_HERE

В конфигурацию с ключом, ограниченным URL-адресом API:

[weblate]
url = https://hosted.weblate.org/api/

[keys]
https://hosted.weblate.org/api/ = YOUR_KEY_HERE

Обзор

wlc [arguments] <command> [options]

Команды фактически указывают, какая операция должна быть выполнена.

Описание

Клиент Weblate — это библиотека Python и инструмент командной строки для удалённого управления Weblate с помощью его API REST для Weblate. Инструмент командной строки может быть вызван как wlc и встроен в wlc.

Аргументы

Программа принимает следующие аргументы, определяющие формат вывода или то, какой надо использовать экземпляр Weblate’а. Они должны быть введены до какой-либо команды.

--format {csv,json,text,html}

Определяет формат вывода.

--url URL

Задаёт URL-адрес API. Переопределяет любое значение, найденное в файле настроек, смотрите раздел Файлы настроек. URL-адрес должен заканчиваться на /api/, например, https://hosted.weblate.org/api/.

--key KEY

Specify the API user key to use. Overrides any value found in the configuration file, see Файлы настроек. You can find your key in your profile on Weblate. When the API URL is loaded from automatically discovered project configuration, --key must be used together with --url. API keys are rejected over non-local http:// URLs by default.

--allow-insecure-http

Allow sending API keys over non-local http:// URLs. Prefer HTTPS or loopback HTTP instead; this option is intended only for legacy deployments where HTTPS is not available. This option only enables insecure HTTP for the current run; omitting it does not disable allow_insecure_http from configuration.

--config PATH

Загружайте конфигурацию только из PATH вместо обнаруженных глобальных и проектных файлов конфигурации, см. Файлы настроек.

--config-section SECTION

Переопределяет используемый раздел файла настроек, смотрите раздел Файлы настроек.

Команды

Доступны следующие команды:

version

Распечатать текущую версию.

list-languages

Вывести список используемых в Weblate языков.

list-projects

Вывести список существующих в Weblate проектов.

list-components

Вывести список существующих в Weblate компонентов.

list-translations

Вывести список существующих в Weblate переводов.

show

Показать объект Weblate (перевод, компонент или проект).

ls

Вывести список объектов Weblate (переводов, компонентов или проектов).

commit

Зафиксировать изменения, внесённые в объект Weblate (перевод, компонент или проект).

pull

Извлечь изменения из удалённого репозитория в объект Weblate (перевод, компонент или проект).

push

Отправить изменения объекта Weblate (перевода, компонента или проекта) в удалённый репозиторий.

reset

Сбросить изменения в объекте Weblate (переводе, компоненте или проекте) для приведения их в соответствие с удалённым репозиторием.

cleanup

Удалить любые неотслеживаемые изменения в объекте Weblate (переводе, компоненте или проекте) для приведения их в соответствие с удалённым репозиторием.

repo

Вывести статус репозитория для данного объекта Weblate (перевода, компонента или проекта).

stats

Вывести подробную статистику по данному объекту Weblate (переводу, компоненту или проекту).

lock-status

Вывести статус блокировки.

lock

Заблокировать компонент в Weblate от дальнейшего перевода.

unlock

Разблокировать перевод компонента Weblate.

changes

Вывести список изменений для данного объекта.

download

Скачать файл перевода.

--convert

Преобразовывать формат файла; если не указан, то ни каких преобразований на стороне сервера не происходит и файл скачивается в том виде, в котором он сохранён в репозитории.

--output

Задаёт файл, в который нужно сохранить файл перевода, если не указан, он будет распечатан в стандартный поток вывода.

upload

Загрузить файл перевода.

--overwrite

Перезаписывать существующие переводы во время загрузки.

--input

Файл, из которого читается содержимое, если не указан, чтение будет производиться со стандартного потока ввода.

--method

Используемый метод загрузки, смотрите Способы импорта.

--fuzzy

Что делать с неточными, отмеченными на правку, переводами (пусто, process или approve)

--author-name

Имя автора, для замены авторизованного в данный момент пользователя

--author-email

Электронная почта автора для переопределения текущей авторизации пользователя

Подсказка

Более подробную информацию по выполнению конкретных команд можно получить с помощью параметра --help, например, wlc ls --help.

Файлы настроек

Если указан --config, wlc загружает только этот файл.

Без --config wlc сначала загружает обнаруженный глобальный файл конфигурации из стандартных, зависящих от платформы мест:

C:\Users\NAME\AppData\Roaming\weblate.ini

Глобальный файл конфигурации в Windows в роуминговом профиле.

C:\Users\NAME\AppData\Local\weblate.ini

Глобальный файл конфигурации в Windows в локальном профиле.

~/.config/weblate

Глобальный файл конфигурации на Unix-подобных системах.

/etc/xdg/weblate

Общесистемный резервный файл конфигурации.

Программа следует спецификации XDG, поэтому вы можете настроить размещение файлов конфигурации с помощью переменных окружения XDG_CONFIG_HOME или XDG_CONFIG_DIRS.

В Windows предпочтительными местами расположения файла настроек являются каталоги APPDATA и LOCALAPPDATA.

После загрузки глобальной конфигурации wlc загружает ближайший файл конфигурации проекта из текущего каталога или его родительских каталогов:

.weblate, .weblate.ini, weblate.ini

Файл конфигурации проекта, размещённый в репозитории.

Загружается только ближайший файл конфигурации проекта. Файлы конфигурации в более удалённых родительских каталогах игнорируются.

Можно настроить следующие параметры, находящиеся в разделе [weblate] (изменить этот раздел вы можете ключом командной строки --config-section):

key

Удалено в версии 1.17: Используйте раздел [keys], чтобы указать ключи, ограниченные для отдельных URL-адресов API, см. Устаревшая конфигурация.

url

Адрес API сервера, по умолчанию установлен http://127.0.0.1:8000/api/.

translation

Путь к переводу по умолчанию — компоненту или проекту.

allow_insecure_http

Allow API keys over non-local http:// URLs, defaults to false. Loopback HTTP URLs, such as http://127.0.0.1:8000/api/, remain allowed for local development without this option. Prefer HTTPS instead of enabling this setting. Automatically discovered project configuration files cannot enable this option; set it in user configuration, an explicit --config file, WLC_ALLOW_INSECURE_HTTP, or --allow-insecure-http. The setting is cumulative: any trusted source that enables insecure HTTP is enough, and false or unset values from command-line or environment sources do not disable it.

retries, timeout, allowed_methods, backoff_factor, status_forcelist

Необязательные настройки повторных попыток HTTP и тайм-аута, передаваемые в urllib3. Используйте allowed_methods для перечисления методов запроса, которые могут быть повторены. Текущие выпуски wlc используют это имя параметра вместо старой опции method_whitelist.

Файл настроек является INI-файлом, например:

[weblate]
url = https://hosted.weblate.org/api/
translation = weblate/application
retries = 3
allowed_methods = PUT,POST,GET
backoff_factor = 0.2
status_forcelist = 429,500,502,503,504
timeout = 30
allow_insecure_http = false

Ключи API хранятся в разделе [keys]:

[keys]
https://hosted.weblate.org/api/ = APIKEY

This allows you to store keys in your personal settings, while using the .weblate configuration in the VCS repository so that wlc knows which server it should talk to. The [keys] lookup is scoped to the exact API URL.

In CI, unscoped keys must pin the API URL explicitly: set both WLC_URL and WLC_KEY, or use --url together with --key.

Переменные окружения

Добавлено в версии 1.18.0.

Изменено в версии 2.0.1: Unscoped API keys require an explicit API URL when project configuration is discovered automatically. API keys are rejected over non-local http:// URLs unless insecure HTTP is explicitly enabled.

The API URL and key can also be configured using environment variables. This is especially useful for CI workflows where WLC_URL pins the destination and WLC_KEY is injected as a secret:

WLC_URL

URL-адрес API

WLC_KEY

API key. When the API URL would otherwise come from automatically discovered project configuration, WLC_KEY is accepted only together with WLC_URL. API keys are rejected over non-local http:// URLs by default.

WLC_ALLOW_INSECURE_HTTP

Set to 1, true, yes, or on to allow API keys over non-local http:// URLs. Prefer HTTPS or loopback HTTP instead. Other values, such as 0 or false, are treated as unset and do not disable allow_insecure_http from configuration.

The same protection applies to command-line arguments: --key is accepted with automatically discovered project configuration only when --url is provided.

The API URL and key configuration precedence (highest to lowest) is:

1. Аргументы командной строки (--url, --key).

2. Переменные окружения (WLC_URL, WLC_KEY).

3. Конфигурация, загруженная из --config, или из обнаруженной глобальной конфигурации плюс ближайшей конфигурации проекта, когда --config не используется.

The insecure HTTP opt-in is enable-only rather than a normal precedence setting. It is enabled when --allow-insecure-http is passed, when WLC_ALLOW_INSECURE_HTTP has a true value, or when allow_insecure_http is enabled in trusted configuration. Automatically discovered project configuration cannot enable it; set it in user configuration or pass an explicit --config file instead.

Примеры

Печать текущей версии программы:

$ wlc version
version: 0.1

Список всех проектов:

$ wlc list-projects
name: Hello
slug: hello
url: http://example.com/api/projects/hello/
web: https://weblate.org/
web_url: http://example.com/projects/hello/

Загрузить файл перевода:

$ wlc upload project/component/language --input /tmp/hello.po

Вы также можете указать, над каким проектом wlc должен работать:

$ cat .weblate
[weblate]
url = https://hosted.weblate.org/api/
translation = weblate/application

$ wlc show
branch: main
file_format: po
source_language: en
filemask: weblate/locale/*/LC_MESSAGES/django.po
git_export: https://hosted.weblate.org/git/weblate/application/
license: GPL-3.0+
license_url: https://spdx.org/licenses/GPL-3.0+
name: Application
new_base: weblate/locale/django.pot
project: weblate
repo: git://github.com/WeblateOrg/weblate.git
slug: application
template:
url: https://hosted.weblate.org/api/components/weblate/application/
vcs: git
web_url: https://hosted.weblate.org/projects/weblate/application/

При такой настройке закоммитить отложенные изменения в текущем проекте проще простого:

$ wlc commit