Klient Weblate

Inštalácia

Klient Weblate je dodávaný samostatne a obsahuje Python modul. Zdrojový kód je udržiavaný v repozitári WeblateOrg/wlc. Na použitie nižšie uvedených príkazov musíte nainštalovať wlc pomocou pip:

pip install wlc

Môžete ho tiež spustiť priamo pomocou uvx:

uvx wlc --help

Rada

Tento wlc môžete tiež použiť ako Python modul, pozri wlc.

Použitie Docker

Klient Weblate je tiež dostupný ako Docker obraz.

Obrazy sú publikované na Docker Hub a v GitHub Container Registry. Nižšie uvedené príklady používajú názov obrazu Docker Hub.

Inštalácia:

docker pull weblate/wlc

Dostupné sú nasledujúce značky:

latest

Najnovšie stabilné vydanie.

Úplná verzia, napríklad 2.2.0

Konkrétne stabilné vydanie.

Hlavná verzia, napríklad 2

Najnovšie stabilné vydanie v danej hlavnej sérii.

edge

Aktuálna vývojová verzia z hlavnej vetvy.

edge-YYYY-MM-DD-COMMIT

Konkrétna vývojová snímka.

Na zostavenie obrazu zo zdrojového checkoutu:

docker build -t weblate/wlc .

Docker kontajner používa predvolené nastavenia klienta Weblate a pripája sa k API nasadenému na localhoste. Nakonfigurujte URL API a kľúč API pomocou bežných argumentov wlc alebo premenných prostredia, napríklad --url, --key, WLC_URL a WLC_KEY. Kľúče API sú predvolene odmietané cez nelokálne URL http://; použite HTTPS, loopback HTTP pre lokálny vývoj alebo explicitne povoľte nezabezpečené HTTP.

Príkaz na spustenie kontajnera používa nasledujúcu syntax:

docker run --rm weblate/wlc [WLC_ARGS]

Príklad:

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

Môžete chcieť odovzdať vašu Konfiguračné súbory Docker kontajneru. Keď váš repozitár obsahuje konfiguráciu projektu, ako je .weblate, najjednoduchší prístup je pridať váš aktuálny adresár ako zväzok /home/weblate:

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

Keď namontovaný repozitár poskytuje URL API v konfigurácii projektu a odovzdáte kontajneru neobmedzený kľúč API, explicitne pripnite aj URL: WLC_KEY vyžaduje WLC_URL a --key vyžaduje --url. Rovnaké párovanie sa vyžaduje pre prepisy --allow-insecure-http a --allow-insecure-ssl.

Ak nakonfigurovaná URL API používa nelokálne http:// a je poskytnutý kľúč API, kontajner odmietne odoslať kľúč, pokiaľ nie je explicitne povolené nezabezpečené HTTP. Uprednostnite HTTPS; pre staršie nasadenia odovzdajte --allow-insecure-http alebo nastavte WLC_ALLOW_INSECURE_HTTP. Certifikáty TLS sú predvolene vždy overované, vrátane loopback URL. Použite --allow-insecure-ssl alebo WLC_ALLOW_INSECURE_SSL iba vtedy, keď overenie certifikátov nemožno povoliť.

Začíname

Najjednoduchší spôsob, ako začať, je vytvoriť osobnú konfiguráciu wlc v ~/.config/weblate (pozri Konfiguračné súbory pre úplné pravidlá objavovania a iné umiestnenia):

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

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

Potom môžete vyvolať príkazy na predvolenom serveri:

wlc ls
wlc commit sandbox/hello-world

Viď aj

Konfiguračné súbory

Staršia konfigurácia

Zmenené vo verzii 1.17: Zastaraná konfigurácia používajúca nerozsahový key už nie je podporovaná.

Zmenené vo verzii 2.2.0: Globálna konfigurácia allow_insecure_http už nie je podporovaná. Nakonfigurujte namiesto toho pôvod v sekcii [insecure_http].

Migrácia starej konfigurácie:

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

Na konfiguráciu s kľúčom obmedzeným na URL API:

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

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

Prehľad

wlc [arguments] <command> [options]

Príkazy skutočne indikujú, ktorá operácia sa má vykonať.

Popis

Klient Weblate je Python knižnica a utilita príkazového riadku na diaľkovú správu Weblate pomocou REST API Weblate. Vyvolajte utilitu príkazového riadku ako wlc; Python API nájdete v wlc.

Argumenty

Program akceptuje nasledujúce argumenty, ktoré definujú formát výstupu alebo ktorú inštanciu Weblate použiť. Tieto sa musia zadať pred akýmkoľvek príkazom.

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

Špecifikujte formát výstupu. Predvolený je text.

Listing commands write results incrementally in all formats as API pages are fetched, reducing memory use for large listings. Normal output buffering still applies. Empty listings produce no output, including in JSON format.

If a later request fails, already written results remain on standard output, and the command reports the error on standard error and exits with a nonzero status. JSON and HTML output can be incomplete in this case. Check the exit status before treating an export as complete.

--version

Vytlačte verziu programu a ukončite. Príkaz version podporuje formátovanie výstupu a môže vytlačiť iba číslo verzie.

--debug

Vytlačte podrobnú komunikáciu HTTP. Hodnoty hlavičky autorizácie sú redigované a telá požiadaviek nie sú logované, ale parametre dotazu áno; nedávajte tajomstvá do parametrov dotazu.

--url URL

Špecifikujte URL API. Prepíše akúkoľvek hodnotu nájdenú v konfiguračnom súbore, pozri Konfiguračné súbory. URL by mala končiť na /api/, napríklad https://hosted.weblate.org/api/.

--key KEY

Špecifikujte kľúč používateľa API, ktorý sa má použiť. Prepíše akúkoľvek hodnotu nájdenú v konfiguračnom súbore, pozri Konfiguračné súbory. Svoj kľúč nájdete vo svojom profile na Weblate. Keď sa URL API načíta z automaticky objavenej konfigurácie projektu, --key sa musí použiť spolu s --url. Kľúče API sú predvolene odmietané cez nelokálne URL http://.

--allow-insecure-http

Povoliť odosielanie kľúčov API cez nelokálne URL http://. Namiesto toho uprednostnite HTTPS alebo loopback HTTP; táto možnosť je určená iba pre staršie nasadenia, kde HTTPS nie je dostupné. Táto možnosť povoluje nezabezpečené HTTP iba pre aktuálne spustenie. Keď URL API pochádza z automaticky objavenej konfigurácie projektu, táto možnosť vyžaduje --url.

--allow-insecure-ssl

Zakázať overovanie certifikátov TLS pre aktuálne spustenie. Certifikáty sú predvolene overované pre každú URL HTTPS, vrátane loopback URL. Keď URL API pochádza z automaticky objavenej konfigurácie projektu, táto možnosť vyžaduje --url.

--config PATH

Načítať konfiguráciu iba z PATH namiesto objavených globálnych a projektových konfiguračných súborov, pozri Konfiguračné súbory.

--config-section SECTION

Vyberá sekciu konfiguračného súboru na použitie namiesto [weblate], pozri Konfiguračné súbory.

Cesty objektov

Príkazy pracujúce s objektom akceptujú jednu z týchto ciest:

PROJECT

Slug projektu.

PROJECT/COMPONENT

Slug komponentu vrátane jeho projektu.

PROJECT/COMPONENT/LANGUAGE

Jazyk prekladu vrátane jeho projektu a komponentu.

UNIT_ID

Numerické ID prekladovej jednotky. Tento formulár akceptujú iba príkazy, ktoré explicitne podporujú jednotky.

Príkazy vyžadujúce objekt používajú nastavenie translation z Konfiguračné súbory, keď je cesta vynechaná. Príkazy ls a download tiež používajú toto nastavenie pred návratom k svojmu správaniu bez objektu. Pre list-components a list-translations vynechaný objekt vždy požaduje zoznam celej inštancie.

Príkazy

Dostupné sú nasledujúce príkazy:

version

Vypíše aktuálnu verziu.

--bare

Vypíše iba číslo verzie.

list-languages

Vypíše všetky jazyky vo Weblate.

list-projects

Vypíše všetky projekty vo Weblate.

list-components

Vypíše všetky komponenty vo Weblate alebo komponenty v špecifikovanom projekte.

list-translations

Vypíše všetky preklady vo Weblate alebo preklady v špecifikovanom komponente.

list-units

Vypíše jednotky v špecifikovanom preklade.

--query QUERY

Filtruje jednotky pomocou syntaxe vyhľadávacieho dotazu.

show

Zobrazí projekt, komponent, preklad alebo jednotku.

delete

Odstráni projekt, komponent, preklad alebo jednotku bez výzvy na potvrdenie.

ls

Vypíše všetky projekty, keď nie je špecifikovaný objekt, komponenty v projekte alebo preklady v komponente.

commit

Zapíše zmeny vykonané v objekte Weblate (preklad, komponent alebo projekt).

pull

Stiahne zmeny zo vzdialeného repozitára do objektu Weblate (preklad, komponent alebo projekt).

push

Odošle zmeny objektu Weblate do vzdialeného repozitára (preklad, komponent alebo projekt).

reset

Resetuje zmeny v objekte Weblate, aby zodpovedali vzdialenému repozitáru (preklad, komponent alebo projekt).

cleanup

Odstráni všetky nesledované zmeny v objekte Weblate, aby zodpovedali vzdialenému repozitáru (preklad, komponent alebo projekt).

repo

Zobrazí stav repozitára pre daný objekt Weblate (preklad, komponent alebo projekt).

stats

Zobrazí podrobné štatistiky pre daný objekt Weblate (preklad, komponent alebo projekt).

lock-status

Zobrazí stav uzamknutia komponentu.

lock

Uzamkne komponent pred ďalším prekladom vo Weblate.

unlock

Odomkne preklad komponentu Weblate.

changes

Zobrazí zmeny pre projekt, komponent alebo preklad.

download

Stiahne prekladové súbory. Pre preklad wlc zapíše súbor do --output alebo do presmerovaného štandardného výstupu. Odmieta písať surový obsah súboru do interaktívneho terminálu.

Pre komponent alebo projekt je --output povinný a je považovaný za adresár. wlc zapíše jeden archív ZIP na komponent. Bez objektu stiahne každý komponent v inštancii Weblate rovnakým spôsobom.

--convert FORMAT

Požaduje konverziu na FORMAT na serveri. Ak nie je špecifikované, nedôjde k žiadnej konverzii.

--output PATH

Špecifikuje výstupný súbor pre preklad alebo výstupný adresár pre komponent, projekt alebo sťahovanie celej inštancie. Na zápis prekladu do štandardného výstupu použite -.

--no-glossary

Vylúči komponenty slovníka zo sťahovania komponentov, projektov a celej inštancie.

upload

Nahrá prekladový súbor.

--overwrite

Prepíše existujúce preložené reťazce. Toto je ekvivalentné --conflicts replace-translated.

--conflicts {ignore,replace-translated,replace-approved}

Vyberá, ako sa riešia konflikty s existujúcimi prekladmi.

--input PATH

Číta obsah z PATH. Ak nie je špecifikované alebo -, obsah sa číta zo štandardného vstupu.

--method {translate,approve,suggest,fuzzy,replace,source,add}

Metóda nahrávania na použitie, pozri Metódy importu. Predvolená je translate.

--fuzzy {process,approve}

Vyberá spracovanie fuzzy reťazcov (označených na úpravu).

--author-name NAME

Meno autora, na prepísanie aktuálne autentifikovaného používateľa

--author-email EMAIL

E-mail autora, na prepísanie aktuálne autentifikovaného používateľa

edit-unit

Aktualizuje prekladovú jednotku. Vyžaduje sa aspoň jedna možnosť aktualizácie.

--target TARGET [TARGET ...]

Nastaví jeden alebo viac preložených reťazcov.

--state STATE

Nastaví stav jednotky: 0 pre prázdne, 10 pre fuzzy, 20 pre preložené alebo 30 pre schválené.

--explanation EXPLANATION

Nastaví vysvetlenie reťazca.

--extra-flags FLAGS

Nastaví ďalšie príznaky reťazca.

Rada

Podrobnejšie informácie o vyvolávaní jednotlivých príkazov získate zadaním --help, napríklad: wlc ls --help.

Konfiguračné súbory

Keď je poskytnutý --config, wlc načíta iba tento súbor.

Bez --config, wlc najprv načíta objavený globálny konfiguračný súbor zo štandardných umiestnení špecifických pre platformu:

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

Globálny konfiguračný súbor na Windows v roamingovom profile.

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

Globálny konfiguračný súbor na Windows v lokálnom profile.

~/.config/weblate

Globálny konfiguračný súbor na systémoch typu Unix.

~/.config/weblate.ini

Alternatívny názov súboru globálnej konfigurácie v systémoch podobných Unixu.

/etc/xdg/weblate

Systémový záložný konfiguračný súbor.

/etc/xdg/weblate.ini

Alternatívny názov systémového záložného konfiguračného súboru.

Program dodržiava špecifikáciu XDG, takže umiestnenie konfiguračných súborov môžete upraviť pomocou premenných prostredia XDG_CONFIG_HOME alebo XDG_CONFIG_DIRS.

Na Windows sú adresáre APPDATA a LOCALAPPDATA preferovanými umiestneniami pre konfiguračný súbor.

Po načítaní globálnej konfigurácie wlc načíta najbližší projektový konfiguračný súbor z aktuálneho adresára alebo jeho rodičov:

.weblate, .weblate.ini, weblate.ini

Projektový konfiguračný súbor umiestnený v repozitári.

Konfigurácia projektu sa načíta po globálnej konfigurácii a prepisuje zodpovedajúce nastavenia. Môže vybrať URL API, predvolený objekt, nastavenia požiadavky a zodpovedajúci kľúč API obmedzený URL, čím umožní klonovanému repozitáru automaticky vybrať jeho server Weblate a preklad.

Načíta sa iba najbližší projektový konfiguračný súbor. Konfiguračné súbory vo vzdialenejších rodičovských adresároch sa ignorujú.

Nasledujúce nastavenia možno nakonfigurovať v sekcii [weblate] (môžete toto prispôsobiť pomocou --config-section):

key

Removed in version 1.17: Použite sekciu [keys] na špecifikáciu kľúčov obmedzených na jednotlivé URL API, pozri Staršia konfigurácia.

url

URL servera API, predvolene http://127.0.0.1:8000/api/.

translation

Predvolená cesta objektu pre príkazy, ktoré jeden akceptujú: projekt, komponent, preklad alebo numerické ID jednotky.

retries, timeout, allowed_methods, backoff_factor, status_forcelist

Nastavenia opakovaných pokusov a časového limitu požiadaviek HTTP. retries je predvolene 0 a backoff_factor 0. status_forcelist je zoznam stavových kódov HTTP oddelených čiarkami, ktoré spúšťajú opakované pokusy, a predvolene je prázdny.

allowed_methods vypisuje metódy, ktoré sa môžu opakovať, oddelené čiarkami alebo bielymi znakmi. Predvolene sú HEAD, DELETE, OPTIONS, PUT a GET. Tieto nastavenia opakovaných pokusov sa odovzdávajú do urllib3.util.Retry.

timeout je časový limit požiadavky v sekundách a predvolene je 300. Aktuálne vydania wlc používajú allowed_methods namiesto staršej možnosti method_whitelist.

Konfiguračný súbor je súbor INI, napríklad:

[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

Kľúče API sú uložené v sekcii [keys]:

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

Toto vám umožňuje ukladať kľúče vo vašich osobných nastaveniach, zatiaľ čo používate konfiguráciu .weblate vo VCS repozitári, takže wlc vie, s ktorým serverom má komunikovať. Vyhľadávanie [keys] je obmedzené na úplnú nakonfigurovanú URL API, nie len na jej sieťový pôvod.

Konfigurácia projektu môže tiež dodať alebo nahradiť zodpovedajúcu položku v [keys]. Neukladajte cenné kľúče API do správy verzií; zvyčajne uchovávajte kľúče v osobnej konfigurácii a v konfigurácii projektu iba URL API a predvolený objekt.

Výnimky nezabezpečeného prenosu sú uložené v sekciách obmedzených pôvodom v dôveryhodnej konfigurácii používateľa:

[insecure_http]
http://legacy.example.com:80 = true

[insecure_ssl]
https://legacy.example.com:443 = true

Pôvod pozostáva zo schémy, normalizovaného názvu hostiteľa a efektívneho portu. Cesta API je ignorovaná, zatiaľ čo rôzne schémy a porty zostávajú izolované. Sekcia [insecure_http] povoľuje kľúče API cez nelokálne HTTP pre zodpovedajúce pôvody. Sekcia [insecure_ssl] zakazuje overovanie certifikátov TLS pre zodpovedajúce pôvody.

Zmenené vo verzii 2.2.0: Certifikáty TLS sú predvolene overované pre všetkých hostiteľov. Konfigurácia nezabezpečeného HTTP a TLS je obmedzená na pôvody. Automaticky objavená konfigurácia projektu nemôže pridávať položky do týchto sekcií ani povoliť odstránené globálne nastavenia. Konfigurácia používateľa a explicitne vybrané súbory --config sú dôveryhodné.

V CI musia neobmedzené kľúče explicitne pripnúť URL API: nastavte oba WLC_URL a WLC_KEY, alebo použite --url spolu s --key.

Premenné prostredia

Added in version 1.18.0.

Zmenené vo verzii 2.0.1: Neobmedzené kľúče API vyžadujú explicitnú URL API, keď sa konfigurácia projektu objaví automaticky. Kľúče API sú odmietané cez nelokálne URL http://, pokiaľ nie je explicitne povolené nezabezpečené HTTP.

Zmenené vo verzii 2.2.0: Prepisy prostredia pre nezabezpečené HTTP a TLS vyžadujú WLC_URL, keď by URL API inak pochádzala z automaticky objavenej konfigurácie projektu.

URL API a kľúč možno nakonfigurovať aj pomocou premenných prostredia. Toto je obzvlášť užitočné pre pracovné postupy CI, kde WLC_URL pripína cieľ a WLC_KEY sa vstrekuje ako tajomstvo:

WLC_URL

URL API

WLC_KEY

Kľúč API. Keď by URL API inak pochádzala z automaticky objavenej konfigurácie projektu, WLC_KEY sa prijíma iba spolu s WLC_URL. Kľúče API sú predvolene odmietané cez nelokálne URL http://.

WLC_ALLOW_INSECURE_HTTP

Nastavte na 1, true, yes alebo on, aby ste povolili kľúče API cez nelokálne URL http://. Namiesto toho uprednostnite HTTPS alebo loopback HTTP. Ostatné hodnoty, ako 0 alebo false, sa považujú za nenastavené. Keď by URL API inak pochádzala z automaticky objavenej konfigurácie projektu, táto premenná sa prijíma iba spolu s WLC_URL.

WLC_ALLOW_INSECURE_SSL

Nastavte na 1, true, yes alebo on, aby ste zakázali overovanie certifikátov TLS. Ostatné hodnoty, ako 0 alebo false, sa považujú za nenastavené. Keď by URL API inak pochádzala z automaticky objavenej konfigurácie projektu, táto premenná sa prijíma iba spolu s WLC_URL.

Rovnaká ochrana platí pre argumenty príkazového riadku: --key, --allow-insecure-http a --allow-insecure-ssl sa akceptujú s automaticky objavenou konfiguráciou projektu iba vtedy, keď je poskytnutý --url.

Priorita konfigurácie URL API a kľúča (od najvyššej po najnižšiu) je:

1. Argumenty príkazového riadku (--url, --key).

2. Premenné prostredia (WLC_URL, WLC_KEY).

3. Konfigurácia načítaná z --config, alebo z objavenej globálnej konfigurácie plus najbližšej projektovej konfigurácie, keď sa --config nepoužíva.

Povolenia nezabezpečeného prenosu sú iba na povolenie, nie sú to bežné nastavenia priority. Sú povolené prepisom z príkazového riadku alebo prostredia, alebo zodpovedajúcim pôvodom v dôveryhodnej sekcii [insecure_http] alebo [insecure_ssl]. Automaticky objavená konfigurácia projektu nemôže pridávať dôveryhodné pôvody.

Bezpečnostný model

Konfigurácia projektu je súčasťou pracovného postupu repozitára a je zámerne dôveryhodná na výber koncového bodu API, predvoleného objektu, nastavení požiadavky a zodpovedajúceho kľúča API obmedzeného URL. Spustenie wlc vnútri repozitára autorizuje jeho najbližšiu projektovú konfiguráciu vybrať server, ktorý prijíma príkazy a nahrávania a poskytuje zobrazovaný alebo stiahnutý obsah. Keď toto nie je žiaduce, použite explicitný dôveryhodný súbor --config.

Klient príkazového riadku akceptuje kľúče API z --key, WLC_KEY alebo zo sekcie [keys]. Nenačíta HTTP autentifikáciu z .netrc alebo súboru pomenovaného NETRC. Poverenia vložené do URL API sú odmietnuté; namiesto toho použite kľúč API. Ostatná integrácia prostredia Requests, vrátane premenných proxy a balíka CA, zostáva povolená.

Model hrozieb wlc dokumentuje úplné hranice dôvery, bezpečnostné vlastnosti, nególy a zodpovednosti downstream. Kópia zodpovedajúca verzii je zahrnutá v zdrojových a wheel distribúciách. Bezpečnostné problémy hláste pomocou procesu hlásenia zraniteľností Weblate.

Príklady

Vypísať aktuálnu verziu programu:

$ wlc version

Vypísať všetky projekty:

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

Nahrať prekladový súbor:

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

Môžete tiež určiť, na ktorom projekte má wlc pracovať:

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

S týmto nastavením je ľahké zapísať čakajúce zmeny v aktuálnom projekte:

$ wlc commit