Клиент Weblate

Установка

Клиент Weblate поставляется отдельно и включает модуль Python. Для использования команд ниже вам необходимо установить wlc с помощью 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

Контейнер Docker использует настройки по умолчанию Клиента Weblate и подключается к API, развёрнутому на localhost. Настройте URL-адрес API и ключ API с помощью обычных аргументов wlc или переменных окружения, например --url, --key, WLC_URL и WLC_KEY. Ключи API по умолчанию отклоняются для нелокальных URL-адресов http://; используйте HTTPS, loopback HTTP для локальной разработки или явно разрешите небезопасный 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

Когда смонтированный репозиторий предоставляет URL-адрес API в конфигурации проекта, а вы передаёте контейнеру ключ API без области действия, также явно укажите URL-адрес: WLC_KEY требует WLC_URL, а --key требует --url.

Если настроенный URL-адрес API использует нелокальный http:// и предоставлен ключ API, контейнер отказывается отправлять ключ, если только небезопасный HTTP явно не включён. Предпочитайте HTTPS; для устаревших развёртываний передайте --allow-insecure-http или установите 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

Укажите ключ пользователя API для использования. Переопределяет любое значение, найденное в файле конфигурации, см. Файлы настроек. Вы можете найти свой ключ в своём профиле на Weblate. Когда URL-адрес API загружается из автоматически обнаруженной конфигурации проекта, --key должен использоваться вместе с --url. Ключи API по умолчанию отклоняются для нелокальных URL-адресов http://.

--allow-insecure-http

Разрешить отправку ключей API через нелокальные URL-адреса http://. Предпочитайте HTTPS или loopback HTTP; эта опция предназначена только для устаревших развёртываний, где HTTPS недоступен. Эта опция включает небезопасный HTTP только для текущего запуска; её пропуск не отключает allow_insecure_http из конфигурации.

--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

Разрешить ключи API через нелокальные URL-адреса http://, по умолчанию false. URL-адреса loopback HTTP, такие как http://127.0.0.1:8000/api/, остаются разрешёнными для локальной разработки без этой опции. Предпочитайте HTTPS вместо включения этого параметра. Автоматически обнаруживаемые файлы конфигурации проекта не могут включить эту опцию; установите её в пользовательской конфигурации, явном файле --config, WLC_ALLOW_INSECURE_HTTP или --allow-insecure-http. Настройка является накопительной: любого доверенного источника, включающего небезопасный HTTP, достаточно, а значения false или не установленные значения из командной строки или окружения не отключают её.

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

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

В CI ключи без области действия должны явно указывать URL-адрес API: установите как WLC_URL, так и WLC_KEY, или используйте --url вместе с --key.

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

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

Изменено в версии 2.0.1: Ключи API без области действия требуют явного URL-адреса API, когда конфигурация проекта обнаруживается автоматически. Ключи API отклоняются для нелокальных URL-адресов http://, если только небезопасный HTTP явно не включён.

URL-адрес API и ключ также можно настроить с помощью переменных окружения. Это особенно полезно для рабочих процессов CI, где WLC_URL указывает пункт назначения, а WLC_KEY вводится как секрет:

WLC_URL

URL-адрес API

WLC_KEY

Ключ API. Когда URL-адрес API в противном случае поступал бы из автоматически обнаруженной конфигурации проекта, WLC_KEY принимается только вместе с WLC_URL. Ключи API по умолчанию отклоняются для нелокальных URL-адресов http://.

WLC_ALLOW_INSECURE_HTTP

Установите 1, true, yes или on, чтобы разрешить ключи API через нелокальные URL-адреса http://. Предпочитайте HTTPS или loopback HTTP вместо этого. Другие значения, такие как 0 или false, рассматриваются как неустановленные и не отключают allow_insecure_http из конфигурации.

Такая же защита применяется к аргументам командной строки: --key принимается с автоматически обнаруженной конфигурацией проекта только при наличии --url.

Приоритет конфигурации URL-адреса API и ключа (от высшего к низшему):

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

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

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

Разрешение небезопасного HTTP является только включением, а не обычной настройкой приоритета. Оно включается, когда передан --allow-insecure-http, когда WLC_ALLOW_INSECURE_HTTP имеет истинное значение или когда allow_insecure_http включён в доверенной конфигурации. Автоматически обнаруженная конфигурация проекта не может включить его; установите его в пользовательской конфигурации или передайте явный файл --config.

Примеры

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

$ 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