버전 관리 통합¶
Weblate는 현재 버전 관리 백엔드로 Git (GitHub 풀 리퀘스트, GitLab 병합 요청, Gitea 풀 리퀘스트, Gerrit 리뷰 요청, Subversion, Bitbucket Cloud 풀 리퀘스트, Bitbucket Data Center 풀 리퀘스트, Azure DevOps 풀 리퀘스트 확장 지원 포함) 및 Mercurial 을 지원합니다.
저장소 접근, 수신 알림, 번역 되돌려 푸시를 결합하는 제공자별 설정 단계는 Code-hosting integrations 을 참조하세요.
저장소 접근¶
사용하려는 VCS 저장소는 Weblate에서 접근할 수 있어야 합니다. 공개적으로 사용 가능한 저장소의 경우 올바른 URL(예: https://github.com/WeblateOrg/weblate.git)을 입력하기만 하면 되지만, 비공개 저장소나 푸시 URL의 경우 설정이 더 복잡하고 인증이 필요합니다.
호스팅 Weblate에서 저장소 접근¶
참고
이 섹션은 호스팅 Weblate(hosted.weblate.org)에 만 적용됩니다. 자체 호스팅 Weblate 인스턴스를 실행 중인 경우 다음 섹션 을 참조하세요.
For GitHub repositories on Hosted Weblate, use the Hosted Weblate app from Weblate’s Connect GitHub account flow whenever possible. The App grants repository access, receives incoming notifications, pushes translation branches, and creates pull requests without inviting the Hosted Weblate weblate user. See GitHub 저장소 접근 for the full setup.
For direct SSH access outside the GitHub App workflow, and for Bitbucket,
Codeberg, and GitLab repositories, Hosted Weblate has a dedicated push user
(with the username weblate, e-mail hosted@weblate.org, and a
name or profile description Weblate push user).
힌트
플랫폼에는 다른 Weblate 인스턴스를 위해 지정된 더 많은 Weblate 사용자가 있을 수 있습니다. 호스팅 Weblate의 올바른 사용자를 찾으려면 이메일 hosted@weblate.org 로 검색하는 것이 좋습니다.
이 사용자를 공동 작업자로 추가하고 저장소에 적절한 권한을 부여해야 합니다(클론에는 읽기 전용이면 충분하고, 푸시에는 쓰기 권한이 필요). 서비스와 조직의 설정에 따라 즉시 적용되거나 Weblate 측에서 확인이 필요할 수 있습니다.
The weblate user on GitHub accepts invitations automatically within five minutes when you intentionally use direct SSH access there. Manual processing might be needed on the other services, so please be patient.
For this direct SSH-user setup, once the weblate user is added to
your repository, you can configure 소스 코드 저장소 and
저장소 푸시 URL using the SSH protocol, for example
git@example.com:group/project.git.
Accessing repositories on code-hosting sites (GitHub, GitLab, Bitbucket, Azure DevOps, …)¶
참고
이 섹션은 자체 호스팅 Weblate 인스턴스에 적용됩니다. 호스팅 Weblate(hosted.weblate.org)를 사용 중인 경우 호스팅 Weblate에서 저장소 접근 를 참조하세요.
자체 호스팅 Weblate의 경우 단일 비공개 저장소는 접근 토큰이 포함된 HTTPS 저장소 URL을 사용해 설정하는 것이 가장 쉬운 경우가 많습니다. Code-hosting integrations 을 참조하세요.
For multiple repositories, create a dedicated code-hosting user associated with a Weblate SSH key (see Weblate SSH 키). This way you associate Weblate SSH key with a single user, because platforms frequently enforce single use of an SSH key. Grant this user access to the repositories, and use SSH URLs to access them (see SSH 저장소).
SSH 저장소¶
비공개 저장소에 접근하는 일반적인 방법 중 하나는 SSH 기반입니다. 이 방식으로 업스트림 저장소에 접근하려면 공개 Weblate SSH 키(Weblate SSH 키 참조)를 승인하세요.
경고
GitHub에서는 각 키를 한 번만 사용할 수 있습니다. GitHub 저장소 접근 및 호스팅 Weblate에서 저장소 접근 를 참조하세요.
Weblate는 첫 연결 시 호스트 키 지문도 저장하며, 나중에 변경된 경우 호스트에 접속하지 않습니다(SSH 호스트 키 확인 참조).
조정이 필요한 경우 Weblate 관리 인터페이스에서 수행하세요:
Weblate SSH 키¶
버전 4.17에서 변경: Weblate는 이제 RSA와 Ed25519 SSH 키를 모두 생성합니다. 새 설정에는 Ed25519 사용을 권장합니다.
Weblate 공개 키는 정보 페이지를 탐색하는 모든 사용자에게 표시됩니다.
관리자는 관리 인터페이스 랜딩 페이지에서(SSH 키 에서) Weblate가 접속에 현재 사용 중인 공개 키를 생성하거나 표시할 수 있습니다.
참고
대응하는 비공개 SSH 키에는 현재 비밀번호를 설정할 수 없으므로 잘 보호되도록 해야 합니다.
힌트
생성된 비공개 Weblate SSH 키의 백업을 만드세요.
SSH 호스트 키 확인¶
Weblate는 첫 접근 시 SSH 호스트 키를 자동으로 저장하고 이후 사용을 위해 기억합니다.
When VCS_RESTRICT_PRIVATE is enabled, Weblate resolves and validates
the repository host before scanning its key and connects ssh-keyscan only
to the approved addresses. The stored key remains associated with the original
hostname.
For Git connections, Weblate also applies HostName and Port from
DATA_DIR/ssh/config before validating and pinning the effective
destination. SSH configuration and SSH_EXTRA_ARGS are trusted
administrator-controlled inputs. They can alter connection routing, and
SSH_EXTRA_ARGS can override Weblate’s address pinning;
administrators are responsible for their effects.
저장소에 연결하기 전에 키 지문을 확인하려면, 관리 인터페이스의 동일 섹션에서 호스트 키 추가 에 접근할 서버의 SSH 호스트 키를 추가하세요. 접근하려는 호스트 이름(예: gitlab.com)을 입력하고 제출 을 누릅니다. 지문이 추가한 서버와 일치하는지 확인하세요.
지문과 함께 추가된 키가 확인 메시지에 표시됩니다:
레거시 SSH 서버 연결¶
최근 OpenSSH 릴리스(예: Weblate Docker 컨테이너에서 사용되는 버전)에서는 기본적으로 SHA-1 해시 알고리즘을 사용하는 RSA 서명을 비활성화합니다. 이 변경은 SHA-1 해시 알고리즘이 암호학적으로 취약하여 USD$50K 미만의 비용으로 선택 접두사 해시 충돌을 만들 수 있기 때문에 이루어졌습니다.
대부분의 사용자에게 이 변경은 눈에 띄지 않으며 ssh-rsa 키를 교체할 필요가 없습니다. OpenSSH는 7.2 릴리스부터 RFC8332 RSA/SHA-256/512 서명을 지원해 왔으며, 기존 ssh-rsa 키는 가능한 경우 자동으로 더 강력한 알고리즘을 사용합니다.
업그레이드되지 않았거나 SSH 프로토콜의 개선 사항을 제대로 따라오지 못한 이전 SSH 구현에 연결할 때 비호환성이 발생할 가능성이 더 높습니다. 이러한 서버에 대한 SSH 연결은 다음과 같은 오류로 실패합니다:
no matching host key type found. Their offer: ssh-rsa
이러한 경우 HostkeyAlgorithms 및 PubkeyAcceptedAlgorithms 옵션을 통해 연결 및/또는 사용자 인증을 허용하기 위해 RSA/SHA1을 선택적으로 다시 활성화해야 할 수 있습니다. 예를 들어, DATA_DIR/ssh/config 의 다음 구문은 단일 대상 호스트에 대해 호스트 및 사용자 인증에 RSA/SHA1을 활성화합니다:
Host legacy-host
HostkeyAlgorithms +ssh-rsa
PubkeyAcceptedAlgorithms +ssh-rsa
레거시 구현이 업그레이드되거나 다른 키 유형(예: ECDSA 또는 Ed25519)으로 재구성될 때까지 RSA/SHA1 활성화는 임시 조치로만 사용하는 것을 권장합니다.
GitHub 저장소¶
자세한 GitHub 저장소 접근은 GitHub 저장소 접근 에서 다룹니다.
GitLab 저장소¶
자세한 GitLab 저장소 접근은 GitLab 저장소 접근 에서 다룹니다.
Weblate 내부 URL¶
다른 (연결된) 구성 요소에서 weblate://project/component 로 배치를 참조하여 서로 다른 구성 요소 간에 하나의 저장소 설정을 공유합니다. 이런 방식으로 연결된 구성 요소는 주요 (참조된) 구성 요소의 VCS 저장소 구성을 사용합니다.
경고
주요 구성 요소를 제거하면 연결된 구성 요소도 제거됩니다.
Weblate는 구성 요소를 생성할 때 일치하는 저장소 설정을 가진 구성 요소를 찾으면 저장소 URL을 자동으로 조정합니다. 구성 요소 구성의 마지막 단계에서 이를 재정의할 수 있습니다.
이를 사용하는 이유:
서버의 디스크 공간을 절약합니다. 저장소가 한 번만 저장됩니다.
업데이트 속도가 빨라집니다. 하나의 저장소만 업데이트됩니다.
Weblate 번역이 포함된 내보내기 저장지가 하나만 있습니다(Git 내보내기 참조).
일부 애드온은 하나의 저장소를 공유하는 여러 구성 요소에서 작동할 수 있습니다(예: Git 커밋 스쿼시).
HTTPS 저장소¶
보호된 HTTPS 저장소에 접근하려면 URL에 사용자 이름과 비밀번호를 포함하세요. 걱정하지 마세요. Weblate는 URL이 사용자에게 표시될 때 이 정보를 제거합니다(저장소 URL을 볼 수 있는 경우에 한함).
예를 들어 인증이 추가된 GitHub URL은 다음과 같습니다: https://user:your_access_token@github.com/WeblateOrg/weblate.git.
URL에 자격 증명을 제공하지 않았는데 저장소에서 이를 요구하는 경우, Git은 다음 오류로 실패합니다:
fatal: could not read Username for 'https://github.com': terminal prompts disabled
버전 5.10.2에서 변경: Weblate가 HTTP 자격 증명이 제공될 때 Git 2.46.0 이상에서 사전 인증을 사용합니다.
이를 통해 Azure DevOps 저장소에 접근할 수 있으며 인증된 저장소에 대한 접근 속도가 빨라집니다.
참고
사용자 이름이나 비밀번호에 특수 문자가 포함된 경우 URL 인코딩해야 합니다. 예: https://user%40example.com:%24password%23@bitbucket.org/….
프록시 사용¶
If you need to access Git repositories over HTTPS using a proxy server, configure the per-protocol environment variables described in HTTP 프록시.
Git¶
힌트
Weblate needs Git 2.46 or newer.
참고
Weblate does not configure or transfer Git LFS objects. Git LFS smudging and pre-push uploads are disabled for Weblate-managed repositories, so LFS tracked files remain pointer files and cannot be used as translation files.
참고
Weblate validates permanent HTTP redirects which stay on the repository hostname and automatically stores the canonical repository URL. The change is recorded in the component history as repository maintenance. Redirects to another hostname have to be configured manually.
더 보기
다양한 종류의 저장소에 접근하는 방법은 저장소 접근 를 참조하세요.
Git force push¶
이는 Git 자체와 정확히 동일하게 작동하며, 유일한 차이점은 항상 force push를 수행한다는 것입니다. 이는 번역용 별도의 저장소를 사용하는 경우에만 사용하기 위한 것입니다.
경고
업스트림 저장소에서 커밋이 쉽게 손실될 수 있으므로 주의하여 사용하세요.
Git 구성 사용자 정의¶
Weblate는 모든 VCS 명령을 HOME=$DATA_DIR/home (DATA_DIR 참조)으로 호출하므로 사용자 구성 편집은 DATA_DIR/home/.git 에서 수행해야 합니다.
GitHub 풀 리퀘스트¶
자세한 GitHub 풀 요청 설정은 GitHub 풀 리퀘스트 에서 다룹니다.
GitLab 병합 요청¶
자세한 GitLab 병합 요청 설정은 GitLab 병합 요청 에서 다룹니다.
Gitea 풀 리퀘스트¶
자세한 Gitea 풀 요청 설정은 Gitea 풀 리퀘스트 에서 다룹니다.
Bitbucket Data Center 풀 리퀘스트¶
자세한 Bitbucket Data Center 풀 요청 설정은 Bitbucket Data Center 풀 리퀘스트 에서 다룹니다.
Bitbucket Cloud 풀 리퀘스트¶
자세한 Bitbucket Cloud 풀 요청 설정은 Bitbucket Cloud 풀 리퀘스트 에서 다룹니다.
Pagure 병합 요청¶
자세한 Pagure 병합 요청 설정은 Pagure 병합 요청 에서 다룹니다.
Gerrit¶
자세한 Gerrit 검토 요청 설정은 Gerrit 리뷰 요청 에서 다룹니다.
Azure DevOps 풀 리퀘스트¶
자세한 Azure DevOps 풀 요청 설정은 Azure DevOps 풀 리퀘스트 에서 다룹니다.
Mercurial¶
Mercurial은 Weblate에서 직접 사용할 수 있는 또 다른 VCS입니다.
참고
모든 Mercurial 버전에서 작동해야 하지만, 때때로 명령줄 인터페이스에 호환되지 않는 변경이 있어 Weblate 통합이 중단될 수 있습니다.
더 보기
다양한 종류의 저장소에 접근하는 방법은 저장소 접근 를 참조하세요.
Subversion¶
Weblate는 subversion 저장소와 상호작용하기 위해 git-svn 을 사용합니다. 이것은 Git 클라이언트가 Subversion을 사용할 수 있게 해주는 Perl 스크립트로, 사용자가 내부 저장소의 전체 클론을 유지하고 로컬에서 커밋할 수 있게 합니다.
참고
Weblate는 Subversion 저장소 레이아웃을 자동으로 감지하려고 시도합니다. 브랜치에 대한 직접 URL 또는 표준 레이아웃(branches/, tags/, trunk/)을 가진 저장소를 모두 지원합니다. 이에 대한 자세한 정보는 git-svn 문서 에서 확인할 수 있습니다. 저장소에 표준 레이아웃이 없고 오류가 발생하는 경우, 저장소 URL에 브랜치 이름을 포함하고 브랜치를 비워 두세요.
Subversion 자격 증명¶
Weblate는 인증서를 미리 수락해야 합니다 (필요한 경우 자격 증명도 포함). DATA_DIR 디렉터리에 삽입됩니다. $HOME 환경 변수를 DATA_DIR 로 설정한 상태에서 svn 을 한 번 사용하여 인증서를 수락하세요:
# Use DATA_DIR as configured in Weblate settings.py, it is /app/data in the Docker
HOME=${DATA_DIR}/home svn co https://svn.example.com/example
더 보기
로컬 파일¶
힌트
내부적으로 Git 을 사용합니다. Git이 설치되어 있어야 하며, 전체 번역 히스토리와 함께 Git을 네이티브로 사용하도록 전환할 수 있습니다.
Weblate는 원격 VCS 없이도 작동할 수 있습니다. 초기 번역은 업로드하여 가져옵니다. 나중에 파일 업로드로 개별 파일을 교체하거나, Weblate에서 직접 번역 문자열을 추가할 수 있습니다 (현재 단일 언어 번역에서만 사용 가능).
백그라운드에서 Weblate가 Git 저장소를 생성하고 모든 변경사항이 추적됩니다. 나중에 번역을 저장하기 위해 VCS를 사용하기로 결정한 경우, Weblate 내에 이미 통합의 기반으로 삼을 수 있는 저장소가 있습니다.