Weblate 클라이언트

설치

The Weblate Client is shipped separately and includes the Python module. The source code is maintained in the WeblateOrg/wlc repository. 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 이미지로도 제공됩니다.

Images are published on Docker Hub and the GitHub Container Registry. The examples below use the Docker Hub image name.

설치:

docker pull weblate/wlc

The following tags are available:

latest

Latest stable release.

Full version, for example 2.2.0

A specific stable release.

Major version, for example 2

Latest stable release in that major series.

edge

Current development version from the main branch.

edge-YYYY-MM-DD-COMMIT

A specific development snapshot.

To build an image from the source checkout:

docker build -t 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. The same pairing is required for the --allow-insecure-http and --allow-insecure-ssl overrides.

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. TLS certificates are always verified by default, including for loopback URLs. Use --allow-insecure-ssl or WLC_ALLOW_INSECURE_SSL only when certificate verification can not be enabled.

시작하기

시작하는 가장 쉬운 방법은 ~/.config/weblate 에 개인 wlc 설정 파일을 만드는 것입니다 (전체 탐색 규칙과 다른 위치는 설정 파일 참조):

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

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

그런 다음 기본 서버에서 명령을 실행할 수 있음:

wlc ls
wlc commit sandbox/hello-world

더 보기

설정 파일

레거시 설정

버전 1.17에서 변경: 범위 지정되지 않은 key 를 사용하는 레거시 설정은 더 이상 지원되지 않습니다.

버전 2.2.0에서 변경: Global allow_insecure_http configuration is no longer supported. Configure an origin in the [insecure_http] section instead.

레거시 설정 마이그레이션:

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

API URL에 범위가 지정된 키가 포함된 설정으로:

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

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

개요

wlc [arguments] <command> [options]

명령은 실제로 수행해야 할 작업을 나타냅니다.

설명

Weblate Client is a Python library and command-line utility to manage Weblate remotely using Weblate의 REST API. Invoke the command-line utility as wlc; see wlc for the Python API.

인수

프로그램은 출력 형식이나 사용할 Weblate 인스턴스를 지정하는 다음 인수를 받습니다. 이 인수는 모든 명령 앞에 입력해야 합니다.

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

Specify the output format. The default is text.

--version

Print the program version and exit. The version command supports output formatting and can print only the version number.

--debug

Print verbose HTTP communication. Authorization header values are redacted and request bodies are not logged, but query parameters are; do not put secrets in query parameters.

--url URL

API 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. When the API URL comes from automatically discovered project configuration, this option requires --url.

--allow-insecure-ssl

Disable TLS certificate verification for the current run. Certificates are verified by default for every HTTPS URL, including loopback URLs. When the API URL comes from automatically discovered project configuration, this option requires --url.

--config PATH

탐색된 전역 및 프로젝트 설정 파일 대신 PATH 에서만 설정을 로드합니다 ( 설정 파일 참조).

--config-section SECTION

Selects the configuration file section to use instead of [weblate], see 설정 파일.

Object paths

Commands that operate on an object accept one of these paths:

PROJECT

Project slug.

PROJECT/COMPONENT

Component slug, including its project.

PROJECT/COMPONENT/LANGUAGE

Translation language, including its project and component.

UNIT_ID

Numeric translation unit ID. Only commands that explicitly support units accept this form.

Commands that require an object use the translation setting from 설정 파일 when the path is omitted. The ls and download commands also use this setting before falling back to their no-object behavior. For list-components and list-translations, an omitted object always requests an instance-wide list.

명령

다음 명령을 사용할 수 있음:

version

현재 버전을 출력합니다.

--bare

Prints only the version number.

list-languages

Lists all languages in Weblate.

list-projects

Lists all projects in Weblate.

list-components

Lists all components in Weblate, or components in the specified project.

list-translations

Lists all translations in Weblate, or translations in the specified component.

list-units

Lists units in the specified translation.

--query QUERY

Filters units using the search query syntax.

show

Shows a project, component, translation, or unit.

delete

Deletes a project, component, translation, or unit without a confirmation prompt.

ls

Lists all projects when no object is specified, components in a project, or translations in a component.

commit

Weblate 객체(번역, 구성요소 또는 프로젝트)에서 이루어진 변경 사항을 커밋합니다.

pull

원격 저장소의 변경 사항을 Weblate 객체(번역, 구성요소 또는 프로젝트)로 가져옵니다.

push

Weblate 객체의 변경 사항을 원격 저장소(번역, 구성요소 또는 프로젝트)에 푸시합니다.

reset

Weblate 객체의 변경 사항을 원격 저장소(번역, 구성요소 또는 프로젝트)와 일치하도록 재설정합니다.

cleanup

Weblate 객체에서 추적되지 않는 변경 사항을 제거하여 원격 저장소(번역, 구성요소 또는 프로젝트)와 일치시킵니다.

repo

지정된 Weblate 객체(번역, 구성요소 또는 프로젝트)의 저장소 상태를 표시합니다.

stats

지정된 Weblate 객체(번역, 구성요소 또는 프로젝트)의 상세 통계를 표시합니다.

lock-status

Displays the lock status of a component.

lock

Weblate에서 구성요소의 추가 번역을 잠급니다.

unlock

Weblate 구성요소의 번역 잠금을 해제합니다.

changes

Displays changes for a project, component, or translation.

download

Downloads translation files. For a translation, wlc writes the file to --output or to redirected standard output. It refuses to write raw file content to an interactive terminal.

For a component or project, --output is required and is treated as a directory. wlc writes one ZIP archive per component. With no object, it downloads every component in the Weblate instance in the same way.

--convert FORMAT

Requests conversion to FORMAT on the server. If unspecified, no conversion happens.

--output PATH

Specifies the output file for a translation or output directory for a component, project, or instance-wide download. Use - to write a translation to standard output.

--no-glossary

Excludes glossary components from component, project, and instance-wide downloads.

upload

번역 파일을 업로드합니다.

--overwrite

Overwrites existing translated strings. This is equivalent to --conflicts replace-translated.

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

Selects how conflicts with existing translations are handled.

--input PATH

Reads content from PATH. If unspecified or -, content is read from standard input.

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

Upload method to use, see 가져오기 방법. The default is translate.

--fuzzy {process,approve}

Selects processing of fuzzy strings (marked for edit).

--author-name NAME

현재 인증된 사용자를 재정의할 저자 이름

--author-email EMAIL

현재 인증된 사용자를 재정의할 저자 이메일

edit-unit

Updates a translation unit. At least one update option is required.

--target TARGET [TARGET ...]

Sets one or more translated strings.

--state STATE

Sets the unit state: 0 for empty, 10 for fuzzy, 20 for translated, or 30 for approved.

--explanation EXPLANATION

Sets the string explanation.

--extra-flags FLAGS

Sets additional string flags.

힌트

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

유닉스 계열 시스템의 전역 설정 파일.

~/.config/weblate.ini

Alternative global configuration filename on Unix-like systems.

/etc/xdg/weblate

시스템 전체 대체 설정 파일.

/etc/xdg/weblate.ini

Alternative system-wide fallback filename.

프로그램은 XDG 사양을 따르므로 환경 변수 XDG_CONFIG_HOME 또는 XDG_CONFIG_DIRS 로 설정 파일의 위치를 조정할 수 있습니다.

Windows에서는 APPDATA 및 LOCALAPPDATA 디렉터리가 설정 파일의 기본 위치입니다.

전역 설정을 로드한 후 wlc 는 현재 디렉터리 또는 상위 디렉터리에서 가장 가까운 프로젝트 설정 파일을 로드함:

.weblate, .weblate.ini, weblate.ini

저장소에 배치된 프로젝트 설정 파일.

Project configuration is loaded after global configuration and overrides matching settings. It can select the API URL, default object, request settings, and a matching URL-scoped API key, allowing a cloned repository to automatically select its Weblate server and translation.

가장 가까운 프로젝트 설정 파일만 로드됩니다. 더 먼 상위 디렉터리의 설정 파일은 무시됩니다.

다음 설정은 [weblate] 섹션에서 구성할 수 있습니다 ( --config-section 으로 사용자 지정 가능):

key

Removed in version 1.17: [keys] 섹션에서 개별 API URL에 범위가 지정된 키를 지정합니다 ( 레거시 설정 참조).

url

API 서버 URL. 기본값은 http://127.0.0.1:8000/api/ 입니다.

translation

Default object path for commands that accept one: a project, component, translation, or numeric unit ID.

retries, timeout, allowed_methods, backoff_factor, status_forcelist

HTTP request retry and timeout settings. retries defaults to 0 and backoff_factor to 0. status_forcelist is a comma-separated list of HTTP status codes that trigger retries and is empty by default.

allowed_methods lists methods that may be retried, separated by commas or whitespace. It defaults to HEAD, DELETE, OPTIONS, PUT, and GET. These retry settings are passed to urllib3.util.Retry.

timeout is the request timeout in seconds and defaults to 300. Current wlc releases use allowed_methods in place of the older method_whitelist option.

설정 파일은 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

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 complete configured API URL, not merely its network origin.

Project configuration can also supply or replace a matching entry in [keys]. Do not commit valuable API keys to version control; normally keep keys in personal configuration and only the API URL and default object in project configuration.

Insecure transport exceptions are stored in origin-scoped sections in trusted user configuration:

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

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

An origin consists of the scheme, normalized hostname, and effective port. The API path is ignored, while different schemes and ports remain isolated. The [insecure_http] section allows API keys over non-local HTTP for matching origins. The [insecure_ssl] section disables TLS certificate verification for matching origins.

버전 2.2.0에서 변경: TLS certificates are verified for all hosts by default. Insecure HTTP and TLS configuration is scoped to origins. Automatically discovered project configuration can neither add entries to these sections nor enable the removed global settings. User configuration and explicitly selected --config files are trusted.

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.

버전 2.2.0에서 변경: Insecure HTTP and TLS environment overrides require WLC_URL when the API URL would otherwise come from automatically discovered project configuration.

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 URL

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. When the API URL would otherwise come from automatically discovered project configuration, this variable is accepted only together with WLC_URL.

WLC_ALLOW_INSECURE_SSL

Set to 1, true, yes, or on to disable TLS certificate verification. Other values, such as 0 or false, are treated as unset. When the API URL would otherwise come from automatically discovered project configuration, this variable is accepted only together with WLC_URL.

The same protection applies to command-line arguments: --key, --allow-insecure-http, and --allow-insecure-ssl are 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 transport opt-ins are enable-only rather than normal precedence settings. They are enabled by a command-line or environment override, or by a matching origin in the trusted [insecure_http] or [insecure_ssl] section. Automatically discovered project configuration cannot add trusted origins.

Security model

Project configuration is part of the repository workflow and is intentionally trusted to select the API endpoint, default object, request settings, and a matching URL-scoped API key. Running wlc inside a repository authorizes its nearest project configuration to select the server that receives commands and uploads and supplies displayed or downloaded content. Use an explicit trusted --config file when this is not desired.

The command-line client accepts API keys from --key, WLC_KEY, or the [keys] section. It does not load HTTP authentication from .netrc or the file named by NETRC. Credentials embedded in API URLs are rejected; use an API key instead. Other Requests environment integration, including proxy and CA-bundle variables, remains enabled.

The wlc threat model documents the complete trust boundaries, security properties, non-goals, and downstream responsibilities. A version-matched copy is included in source and wheel distributions. Report security issues using the Weblate vulnerability reporting process.

예제

현재 프로그램 버전 출력:

$ wlc version

모든 프로젝트 나열:

$ 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