지속적 현지화¶

번역이 개발 흐름을 긴밀하게 따라갈 수 있는 인프라가 갖추어져 있습니다. 이 방식으로 번역자는 출시 직전에 대량의 새 텍스트를 처리하는 대신 항상 번역 작업을 수행할 수 있습니다.

Weblate와 통합 describes basic ways to integrate your development with Weblate. Code-hosting integrations lists provider-specific setup steps for common code-hosting sites.

프로세스는 다음과 같습니다:

개발자가 변경 사항을 만들고 VCS 저장소에 푸시합니다.
선택적으로 번역 파일이 업데이트됩니다. 새 문자열 도입 참조.
Weblate가 VCS 저장소에서 변경 사항을 가져오고, 번역 파일을 구문 분석하며, 데이터베이스를 업데이트합니다. 저장소 업데이트 참조.
번역자가 Weblate 웹 인터페이스를 사용하여 번역을 제출하거나 오프라인 변경 사항을 업로드합니다.
번역자가 완료하면 Weblate가 변경 사항을 로컬 저장소에 커밋합니다(지연 커밋 참조).
변경사항이 업스트림 저장소로 다시 푸시됩니다(Weblate에서 변경사항 푸시 참조).

힌트

Upstream code-hosting site is not necessary, you can use Weblate with 로컬 파일 where there is only the repository inside Weblate.

저장소 업데이트¶

소스에서 백엔드 저장소를 업데이트하는 방법을 설정해야 합니다.

Use 알림 후크 to integrate with the majority of common code-hosting services, see Code-hosting integrations. You must also 후크 활성화 for this to work. Hook deliveries update components whose repository URL matches the payload; see Matching webhook targets.
저장소 관리에서 또는 Weblate의 REST API 또는 Weblate 클라이언트 를 사용하여 수동으로 업데이트를 트리거합니다
AUTO_UPDATE 를 활성화하여 Weblate 인스턴스의 모든 구성 요소를 자동으로 업데이트합니다
updategit 을 실행합니다(프로젝트 선택 또는 --all 로 모두 업데이트)

Weblate가 저장소를 업데이트할 때마다 업데이트 후 애드온이 트리거됩니다. 애드온 참조.

Matching webhook targets¶

Forge webhooks update components whose 소스 코드 저장소 exactly matches a repository URL from the payload (HTTPS or SSH as reported by the forge, plus common variants such as a trailing slash).

Generic forge webhook endpoints are compatibility interfaces, and ordinary repository deliveries are not cryptographically authenticated. Legacy GitHub App deliveries containing installation data are an exception: the generic GitHub endpoint verifies their signature using GITHUB_LEGACY_APP_WEBHOOK_SECRET. Repository matching does not apply project or component access control because webhooks also need to update private projects and restricted components. Their JSON responses include diagnostic counts for repository, branch, and enabled-hook matches. Successful responses also include the full project/component slugs and absolute API URLs of updated components. Supplying a matching repository URL can therefore confirm that a repository is registered and reveal these identifiers.

Components managed through an authenticated integration are excluded from generic webhook matching and its diagnostic counts. Currently this applies to the GitHub (via Weblate GitHub app) VCS backend. These components receive notifications only through their dedicated tokenized and signed GitHub App webhook URL. Future authenticated integrations are expected to use the same separation.

The returned API URLs do not grant access to the components. The web interface and API continue to enforce normal access control, and webhook responses do not include repository content, translations, or credentials. Where available, prefer an authenticated integration such as App webhook URL.

버전 2026.9에서 변경: Host and path suffix fallback matching was removed. If updates stop, align 소스 코드 저장소 with a URL from the forge webhook payload.

병합 충돌 방지¶

Weblate의 병합 충돌은 동일한 파일이 Weblate 내부와 외부에서 모두 변경될 때 발생합니다. 상황에 따라 도움이 될 수 있는 여러 가지 접근 방식이 있습니다:

Weblate에서만 번역 파일을 변경하여 병합 충돌 방지
외부 변경 시 Weblate를 잠금으로써 병합 충돌 방지
Git 작업에 집중하여 병합 충돌 방지

Weblate에서만 번역 파일을 변경하여 병합 충돌 방지¶

단일 언어 파일에서는 Weblate 외부 편집을 피하는 것이 쉽습니다. Weblate 내에서 새 문자열을 추가하고 파일 편집 전체를 거기서 처리할 수 있습니다. 이중 언어 파일의 경우 일반적으로 소스 코드에서 번역 가능한 파일을 생성하는 메시지 추출 프로세스가 있습니다. 어떤 경우에는 이를 두 부분으로 나눌 수 있습니다:

추출이 템플릿을 생성합니다(예: gettext POT는 xgettext 를 사용하여 생성).
추가 프로세스가 이를 실제 번역에 병합합니다(gettext PO 파일은 msgmerge 를 사용하여 업데이트).

두 번째 단계를 Weblate 내에서 수행할 수 있으며, 이 작업 전에 모든 보류 중인 변경 사항이 포함되도록 보장합니다.

외부 변경 시 Weblate를 잠금으로써 병합 충돌 방지¶

Weblate를 업데이트 프로세스에 통합하여 Weblate 외부에서 파일을 업데이트하기 전에 변경 사항을 플러시하려면, Weblate의 REST API 를 사용하여 Weblate가 모든 보류 중인 변경 사항을 강제로 푸시하고 사용자가 측에서 변경하는 동안 번역을 잠그도록 할 수 있습니다.

업데이트를 수행하는 스크립트는 다음과 같을 수 있습니다:

# Lock Weblate translation
wlc lock
# Push changes from Weblate to upstream repository
wlc push
# Pull changes from upstream repository to your local copy
git pull
# Update translation files, this example is for Django
./manage.py makemessages --keep-pot -a
git commit -m 'Locale updates' -- locale
# Push changes to upstream repository
git push
# Tell Weblate to pull changes (not needed if Weblate follows your repo
# automatically)
wlc pull
# Unlock translations
wlc unlock

동일한 저장소를 공유하는 여러 구성 요소가 있는 경우 각각 별도로 잠가야 합니다:

wlc lock foo/bar
wlc lock foo/baz
wlc lock foo/baj

참고

이 예시는 Weblate 클라이언트 를 사용하며, Weblate를 원격으로 제어하려면 구성(API 키)이 필요합니다. Weblate 클라이언트 대신 curl과 같은 HTTP 클라이언트를 사용하여 이를 달성할 수도 있습니다. Weblate의 REST API 참조.

저장소 유지보수¶

저장소 유지보수 보기는 프로젝트, 구성 요소 또는 번역의 저장소 상태를 표시하고 권한이 있는 사용자가 사용자 인터페이스에서 유지보수 작업을 실행할 수 있게 합니다.

동일한 작업은 Weblate의 REST API 를 사용하거나 지원되는 부분 집합에 대해 Weblate 클라이언트 를 사용하여 트리거할 수도 있습니다.

개별 작업의 가용성은 권한, 구성된 버전 관리 시스템, 푸시 구성 여부, 선택된 객체의 잠금 가능 여부에 따라 다릅니다.

The File management actions are available only from Repository maintenance for an individual translation. These actions rewrite that translation file and commit the result; they are not project-wide or component-wide operations.

Operations that read repository content, such as updating, resetting, or rescanning, also reconcile translation files in Weblate. Added or removed translation files are reflected after this processing finishes. Glossary language synchronization and cleanup are described in Language files and synchronization.

작업	작동 방식	일반적인 용도
커밋	Weblate에 저장된 보류 중인 변경 사항을 로컬 저장소에 커밋합니다.	다른 곳에서 저장소 작업을 하기 전에 보류 중인 Weblate 변경 사항을 플러시합니다.
푸시	커밋된 로컬 저장소 변경 사항을 구성된 업스트림에 푸시합니다.	자동 푸시가 비활성화되거나 지연될 때 커밋된 번역을 업스트림에 전송합니다.
업데이트	Fetches upstream changes, integrates them using the component’s configured 병합 스타일, and reconciles translation files.	기본 통합 전략을 사용하여 Weblate를 업스트림과 동기화합니다.
병합으로 업데이트	업스트림 변경 사항을 가져와 명시적 병합으로 통합합니다.	단일 업데이트에 대해 기본 병합 스타일을 재정의합니다.
리베이스로 업데이트	업스트림 변경 사항을 가져와 로컬 Weblate 커밋을 업스트림 위에 리베이스합니다.	워크플로우에 맞는 경우 히스토리를 선형으로 유지합니다.
빨리 감기 없이 병합으로 업데이트	빨리 감기가 가능한 경우에도 업스트림 변경 사항을 가져와 명시적 병합 커밋을 생성합니다.	감사 또는 브랜치 관리 목적으로 병합 커밋을 보존합니다.
잠금 / 잠금 해제	번역자가 Weblate에서 추가 변경을 하지 못하도록 방지하거나 허용합니다.	Weblate 외부에서 저장소 유지 관리를 수행하는 동안 번역 변경 사항을 고정합니다.
초기화 및 삭제	Resets Weblate’s local repository to upstream, discards pending Weblate changes, and reconciles translation files.	업스트림이 로컬 Weblate 저장소 상태를 덮어쓰는 경우에 사용합니다.
초기화 및 재적용	Resets Weblate’s local repository to upstream, reconciles translation files, and reapplies pending translations. See 초기화 및 재적용 복구 동작.	보류 중인 Weblate 번역을 유지하면서 분기된 히스토리를 복구합니다.
정리	로컬 저장소 체크아웃에서 추적되지 않는 파일과 오래된 브랜치를 제거합니다.	Weblate 체크아웃의 잔여 파일이나 오래된 저장소 상태를 정리합니다.
동기화	Weblate가 알려진 모든 번역을 저장소 파일에 다시 쓰도록 강제합니다.	저장소 파일이 데이터베이스 상태와 동기화되지 않은 경우를 복구합니다.
재검색	Re-reads translation files from the local repository into Weblate and removes translations whose files no longer match the component configuration.	수동 저장소 작업이나 파일 생성 후 파일 변경사항을 가져옵니다.
Remove duplicates	Removes repeated strings with the same identifier from one translation file.	Repair duplicate strings reported by Weblate when the file contains repeated units.
Cleanup unused	Removes strings no longer present in the base file from one translation file. The 번역 파일 정리 add-on can perform this automatically.	Run a one-time cleanup without installing the add-on.
Remove obsolete	Removes obsolete strings from one PO translation file.	Run a one-time PO cleanup without enabling automatic obsolete string removal.

초기화 및 재적용 복구 동작¶

초기화 및 재적용 작업은 로컬 저장소 상태를 업스트림에 맞게 초기화하면서 Weblate의 보류 중인 번역을 유지합니다.

이 작업은 초기화 후 대상 언어 파일이 여전히 존재하거나 Weblate가 유효한 신규 번역의 템플릿 를 사용하는 등 해당 구성요소에 대해 파일을 생성할 수 있는 경우에만 보류 중인 번역을 복원할 수 있습니다.

이러한 조건 중 어느 것도 충족되지 않으면 Weblate는 보류 중인 변경사항을 데이터베이스에 보존하고 나중에 일반적인 구문 분석 오류로 실패하는 대신 복구 오류를 보고합니다.

Git 작업에 집중하여 병합 충돌 방지¶

Weblate가 번역 파일 변경의 유일한 소스인 경우에도, Git 커밋 스쿼시 애드온을 사용하거나, 병합 스타일 이 Rebase 로 설정되었거나, Weblate 외부에서 커밋을 스쿼시하는 경우 (예: 풀 리퀘스트를 병합할 때) 충돌이 발생할 수 있습니다.

이 경우 병합 충돌의 원인은 다릅니다. 이전 Weblate 커밋을 업스트림에 병합한 뒤 Weblate에 새 로컬 커밋이 생길 수 있습니다. 병합이 자동화되어 있지 않고 변경사항이 사람의 검토를 받느라 며칠 또는 몇 주 동안 대기하는 경우 보통 이런 일이 발생합니다. 그러면 Git이 업스트림 변경사항을 Weblate의 변경사항과 일치하는 것으로 더 이상 식별하지 못해 리베이스 수행을 거부할 수 있습니다.

Weblate 변경사항을 스쿼시 병합하면 이 상황에서 복구하기가 더 어려워집니다. 스쿼시 병합은 업스트림 기록에 개별 Weblate 커밋을 보존하는 대신 새 커밋을 만듭니다. Weblate는 여전히 로컬 저장소에 원래 커밋을 가지고 있지만, Git은 업스트림에 이미 그 커밋들이 포함되어 있음을 더 이상 증명할 수 없습니다. 충돌도 수동으로 해결했다면 파일 내용이 두 저장소 모두와 달라질 수 있어, 풀 리퀘스트가 업스트림에 병합된 뒤에도 Weblate가 계속 업데이트에 실패할 수 있습니다.

스쿼시 병합 때문에 업스트림에 Weblate 커밋이 더 이상 포함되어 있지 않다면 저장소 업데이트만으로는 충분하지 않을 수 있습니다. 보류 중인 번역을 유지하면서 Weblate를 업스트림으로 재설정하려면 저장소 유지관리 의 재설정 후 다시 적용 을 사용하세요. 초기화 및 재적용 복구 동작 를 참조하세요. 업스트림이 Weblate의 로컬 변경사항을 완전히 대체해야 할 때만 재설정 후 폐기 를 사용하세요.

이 문제를 해결하려면 풀 리퀘스트를 병합할 때 Weblate의 보류 중인 변경사항을 최소화하거나, 변경사항을 스쿼시하지 않음으로써 충돌을 완전히 피해야 합니다.

다음은 이를 방지하기 위한 몇 가지 방법임:

Weblate 변경사항에는 Git 커밋 스쿼시 나 스쿼시 병합을 사용하지 마세요. 스쿼시가 병합 후 Git이 변경사항을 더 이상 인식하지 못하는 원인이 될 수 있습니다.
Weblate 외부에서 충돌을 해결할 때는 일반 병합 커밋으로 Weblate 커밋을 병합하고 그 결과를 업스트림에 푸시하세요. 충돌 해결 풀 리퀘스트를 스쿼시 병합하지 마세요.
Weblate가 병합 전에 보류 중인 변경사항을 커밋하도록 합니다. 이렇게 하면 풀 리퀘스트가 모든 변경사항으로 업데이트되고 두 저장소가 동기화됩니다.
Weblate의 리뷰 기능 ( 번역 워크플로 참조)을 사용하여 CI 통과 후 GitHub 풀 리퀘스트를 자동으로 병합할 수 있습니다.
GitHub 풀 리퀘스트가 리뷰 중일 때 Weblate에서 잠금을 사용하여 변경을 방지합니다.

Weblate 클라이언트

Code-hosting notifications¶

GitHub, GitLab, Bitbucket, Pagure, Azure Repos, Gitea, Forgejo, Gitee에 대한 공급자별 앱 및 웹훅 지침은 Code-hosting integrations 에서 다룹니다.

공급자별 알림¶

이 레거시 앵커는 호환성을 위해 유지됩니다. 현재 공급자별 앱 및 웹훅 설정은 Code-hosting integrations 에 문서화되어 있습니다.

매일 밤 저장소 자동 업데이트¶

Weblate는 나중에 변경사항을 병합할 때 성능을 향상시키기 위해 매일 밤 원격 저장소를 자동으로 가져옵니다. AUTO_UPDATE 를 활성화하면 이를 야간 병합도 수행하도록 선택할 수 있습니다.

Weblate에서 변경사항 푸시¶

각 번역 구성 요소에는 푸시 URL을 설정할 수 있으며(저장소 푸시 URL 참조), 이 경우 Weblate는 변경 사항을 원격 저장소로 푸시할 수 있습니다. 또한 Weblate를 설정하여 커밋할 때마다 변경 사항을 자동으로 푸시하도록 할 수도 있습니다(커밋 시 푸시 참조).

푸시 옵션 표와 공급자별 풀, 병합, 리뷰 요청 워크플로는 Weblate에서 변경사항 푸시 를 참조하세요.

SSH 키 설정은 저장소 접근 를, Weblate가 변경사항을 커밋하는 시기에 대한 정보는 지연 커밋 를 참조하세요.

보호된 브랜치¶

보호된 브랜치에서 Weblate를 사용하는 경우, 풀 리퀘스트를 사용하고 번역에 대해 실제 리뷰를 수행하도록 구성할 수 있습니다 (알지 못하는 언어에 대해서는 문제가 될 수 있습니다). 대안으로 Weblate 푸시 사용자에 대해 이 제한을 면제할 수도 있습니다.

예를 들어 GitHub에서는 저장소 설정에서 이 작업을 수행할 수 있음:

다른 사용자와 소통하기¶

Weblate는 API를 사용하여 다른 사용자와 쉽게 소통할 수 있습니다.

Weblate의 REST API

지연 커밋¶

Weblate의 동작은 가능한 경우 같은 작성자의 커밋을 하나의 커밋으로 그룹화합니다. 이렇게 하면 커밋 수가 크게 줄어들지만, 예를 들어 병합을 위해 VCS 저장소를 동기화하려는 경우 명시적으로 커밋을 수행하도록 지시해야 할 수 있습니다 (이것은 기본적으로 관리자 그룹에 허용됩니다. 권한 목록 참조).

이 모드에서는 다음 조건 중 하나가 충족되면 변경사항이 커밋됨:

다른 사람이 이미 변경된 문자열을 변경하는 경우.
업스트림에서 병합이 발생하는 경우.
명시적인 커밋이 요청된 경우.
파일 다운로드가 요청된 경우.
변경사항이 구성요소 설정 에 정의된 커밋할 변경사항의 경과 시간 기간보다 오래된 경우.

힌트

커밋은 모든 구성요소에 대해 생성됩니다. 따라서 많은 구성요소가 있는 경우 여전히 많은 커밋이 표시됩니다. 이 경우 Git 커밋 스쿼시 애드온을 활용할 수 있습니다.

시간 확인 없이 더 자주 커밋하려면 커밋을 수행하는 정기 작업을 예약할 수 있습니다. Django 관리자 인터페이스 의 주기적 작업 을 사용하여 이 작업을 수행할 수 있습니다. 먼저 원하는 간격 (예: 120초)을 만듭니다. 그런 다음 새 주기적 작업을 추가하고 weblate.trans.tasks.commit_pending 을 작업 으로 선택하고 {"hours": 0} 을 키워드 인수 로, 원하는 간격을 지정합니다.

스크립트를 사용한 저장소 처리¶

Weblate가 저장소와 통신하는 방식을 사용자 정의하려면 애드온 을 활용하세요. 애드온을 통해 외부 스크립트를 실행하는 방법은 애드온에서 스크립트 실행 를 참조하세요.

구성요소 간 번역 동일하게 유지¶

여러 번역 구성요소가 있는 경우, 같은 문자열에 같은 번역이 적용되도록 하고 싶을 수 있습니다. 이는 여러 수준에서 달성할 수 있습니다.

번역 전파¶

번역 전파 허용 이 활성화된 경우 (기본값. 구성요소 설정 참조) 모든 새 번역은 일치하는 문자열이 있는 모든 구성요소에서 자동으로 수행됩니다. 이러한 번역은 모든 구성요소에서 현재 번역 중인 사용자에 올바르게 귀속됩니다.

전파 전제조건:

모든 구성요소가 단일 프로젝트에 있어야 합니다 (구성요소를 연결하는 것만으로는 충분하지 않습니다).
번역 전파 허용 을 활성화하여 일치하는 문자열에 대해 번역을 자동으로 재사용합니다.
번역 전파는 단일 언어 번역 형식의 경우 키가 일치해야 하므로, 번역 키를 만들 때 이 점을 유의하세요.
문자열은 번역 중에 전파되며, 저장소에서 로드된 문자열은 전파되지 않습니다.

팁

이 기능은 현재 제한적이며, 더 보편적으로 만들고자 합니다. https://github.com/WeblateOrg/weblate/issues/3166에서 피드백을 공유해 주세요.

일관성 검사¶

일관성 없음 검사는 문자열이 다를 때마다 트리거됩니다. 이를 활용하여 이러한 차이를 수동으로 검토하고 올바른 번역을 선택할 수 있습니다.

자동 번역¶

다른 구성요소를 기반으로 한 자동 번역은 구성요소 간 번역을 동기화하는 방법이 될 수 있습니다. 수동으로 트리거할 수 있습니다(자동 번역 참조) 또는 애드온을 사용하여 저장소 업데이트 시 자동으로 실행되도록 할 수 있습니다(자동 번역 참조).