Клієнт 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: Застаріла конфігурація з використанням ключа без області видимості більше не підтримується.

Перенести застарілу конфігурацію:

[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 Client — це бібліотека Python та утиліта командного рядка для віддаленого керування Weblate за допомогою Програмний інтерфейс REST Weblate. Утиліту командного рядка можна викликати як wlc, вона вбудована в wlc.

Аргументи¶

Програма приймає вказані нижче аргументи, які визначають формат виведення даних або екземпляр Weblate, яким слід скористатися. Ці аргументи слід вводити перед будь-якою командою.

--format {csv,json,text,html}¶: Вказати формат виведення даних.

--url 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¶: Вказує файл для зберігання виведених даних. Якщо файл не вказано, дані буде виведено до стандартного виведення (stdout).

upload¶

Вивантажує файл перекладу.

--overwrite¶: Перезаписати наявні переклади під час вивантаження.

--input¶: Файл, з якого читатимуться дані. Якщо не вказано, дані буде прочитано зі stdin.

--method¶: Спосіб вивантаження, яким слід скористатися. Див. Способи імпортування.

--fuzzy¶: Обробка неточних (позначених для редагування) перекладів (empty, 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: Removed in version 1.17: Використовуйте розділ [keys], щоб вказати ключі, що використовуються для окремих URL-адрес API, див. Застаріла конфігурація.

url: Адреса сервера програмного інтерфейсу, типово, 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.

Змінні середовища¶

Added in version 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¶: Адреса 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:

Аргументи командного рядка (--url, --key).
Змінні середовища (WLC_URL, WLC_KEY).
Конфігурація завантажується з --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