Weblate와 통합¶

Weblate 기본¶

프로젝트 및 구성요소 구조¶

Weblate에서 번역은 프로젝트와 구성요소로 구성됩니다. 각 프로젝트에는 여러 구성요소가 포함될 수 있으며, 구성요소에는 개별 언어로의 번역이 포함됩니다. 구성요소는 하나의 번역 가능한 파일(예: GNU gettext PO (Portable Object) 또는 Android 문자열 리소스)에 해당합니다. 프로젝트는 구성요소를 논리적 집합으로 구성하는 데 도움이 됩니다(예: 하나의 애플리케이션에서 사용되는 모든 번역을 그룹화).

또한 프로젝트 내 구성요소는 카테고리를 사용하여 구조화할 수 있습니다. 구성요소는 카테고리에 속할 수 있으며, 카테고리는 중첩할 수 있습니다.

내부적으로 각 프로젝트에서는 공통 문자열에 대한 번역이 기본적으로 프로젝트 내 다른 구성요소에 전파됩니다. 이를 통해 반복적이고 다중 버전 번역의 부담이 줄어듭니다. 번역이 달라져야 하는 경우 번역 전파 허용 을 사용하여 구성요소 설정 별로 번역 전파를 비활성화할 수 있습니다.

저장소 연동¶

Weblate는 업스트림 버전 제어 저장소와 통합되도록 구축되었습니다. 지속적 현지화 에서 구성 요소와 변경 사항의 흐름을 설명합니다.

아키텍처 개요 에서 Weblate의 내부 작동 방식을 설명합니다.

사용자 귀속¶

Weblate는 번역자가 작성한 번역을 이름과 이메일을 사용하여 버전 관리 저장소에 올바르게 보관합니다. 실제 이메일이 커밋에 첨부되면 분산 버전 관리 원칙을 따르며, GitHub와 같은 서비스는 Weblate에서 작성한 기여를 GitHub 프로필과 연결할 수 있습니다.

이 기능은 버전 관리 커밋에 이메일 주소를 공개하는 오용 위험을 수반합니다. 더욱이, 이러한 커밋이 GitHub와 같은 공개 호스팅 플랫폼에 게시되면 사실상 삭제할 방법이 없습니다. Weblate는 이러한 문제를 방지하기 위해 계정 에서 개인 커밋 이메일을 선택할 수 있도록 지원합니다.

따라서 관리자는 Weblate를 구성할 때 다음 사항을 고려해야 합니다:

이러한 이메일 사용은 해당 문서가 필요한 경우 서비스 약관에 명확하게 설명되어야 합니다. 법적 모듈 이 이에 도움이 될 수 있습니다.
PRIVATE_COMMIT_EMAIL_OPT_IN 를 사용하면 이메일을 기본적으로 비공개로 설정할 수 있습니다.

현지화 프로젝트를 Weblate로 가져오기¶

Weblate는 핵심 기능으로 VCS 통합을 염두에 두고 개발되었으므로 가장 쉬운 방법은 Weblate에 저장소 접근 권한을 부여하는 것입니다. 가져오기 프로세스가 번역을 Weblate 구성요소로 구성하는 과정을 안내합니다.

또는 통합 없이 모든 번역이 포함된 로컬 전용 저장소를 Weblate가 설정하도록 할 수 있습니다.

Weblate에서 업데이트된 번역 가져오기¶

Weblate는 업데이트된 문자열을 데이터베이스에 저장하고 로컬 버전 관리 저장소에 커밋합니다. (Git 내보내기 가 활성화된 경우) Weblate 저장소를 추가 원격 저장소로 추가하고 번역 업데이트를 가져올 수 있습니다.

이에 앞서 Weblate에서 이루어진 보류 중인 로컬 변경 사항을 커밋할 수 있습니다 ( 지연 커밋 참조). 사용자 인터페이스 (저장소 유지보수) 또는 Weblate 클라이언트 를 사용한 명령줄에서 수행할 수 있습니다.

Weblate에 저장소 푸시 접근 권한을 부여하고 구성요소 설정 에서 저장소 푸시 URL 를 구성하면 변경사항 푸시를 자동화할 수 있습니다. Weblate에서 변경사항 푸시 를 참조하세요.

또는 Weblate의 REST API 를 사용하여 번역을 업데이트하여 원격 VCS 저장소의 업스트림 최신 버전과 일치시킬 수 있습니다.

원격 변경 사항을 Weblate로 가져오기¶

원격 VCS 저장소에서 최근 업데이트된 문자열을 Weblate로 가져오려면 Weblate가 업스트림 저장소에서 풀하도록 허용하세요. 사용자 인터페이스 (저장소 유지보수) 또는 Weblate 클라이언트 를 사용한 명령줄에서 수행할 수 있습니다.

저장소에 웹훅을 설정하여 새 커밋이 있을 때마다 Weblate를 트리거하면 자동화할 수 있습니다. 자세한 내용은 저장소 업데이트 를 참조하세요.

VCS 통합을 사용하지 않는 경우 UI 또는 Weblate의 REST API 를 사용하여 번역을 업데이트하여 코드베이스와 일치시킬 수 있습니다.

Monitoring translation progress¶

Use the project metrics endpoint to track translation progress from external integrations. It returns statistics for all visible components and languages in a single request and supports JSON, CSV, and OpenMetrics formats.

The OpenMetrics representation can be scraped by Prometheus-compatible monitoring systems without polling the statistics endpoint for each translation.

새 문자열 추가¶

번역 파일이 코드와 함께 원격 VCS에 저장되어 있으면 개발자가 새 문자열을 도입하는 기존 워크플로가 있을 가능성이 높습니다. 문자열을 추가하는 모든 방법이 인식되지만, 오류 도입을 방지하기 위해 원문 문자열의 품질 관문 를 사용하는 것을 고려하세요.

번역 파일이 코드와 분리되어 있는 경우 다음 방법으로 Weblate에 새 문자열을 도입할 수 있습니다.

수동으로 원문 언어의 작업 메뉴에서 새 번역 문자열 추가 를 사용합니다. 양식 내에서 단수 및 복수 라디오 버튼 중 선택할 수 있습니다. 추가할 새 번역 문자열의 적절한 형태를 선택하세요.
프로그래밍 방식으로 API POST /api/translations/(string:project)/(string:component)/(string:language)/units/ 를 사용.
원문 파일을 기존 번역 파일 바꾸기 (기존 문자열을 덮어쓰므로 파일에 이전 문자열과 새 문자열이 모두 포함되도록 하세요) 또는 새 문자열 추가 로 업로드하여 추가. 가져오기 방법 참조.

참고

Weblate에서 문자열을 추가하려면 문자열 관리 가 필요합니다.

대상 언어 파일 업데이트¶

단일 언어 파일 ( 현지화 파일 형식 참조)의 경우 Weblate는 단일언어 기반 언어 파일 에 있지만 실제 번역에는 없는 새 번역 문자열을 추가할 수 있습니다. 그러나 예상치 못한 결과가 발생할 수 있으므로 오래된 문자열을 자동으로 정리하지 않습니다. 그래도 정리하려면 요구 사항에 따라 정리를 처리하는 번역 파일 정리 애드온을 설치하세요.

Weblate는 원문이 변경될 때 이중 언어 파일도 업데이트하지 않으므로 po 파일을 pot 에서 업데이트해야 하는 경우 두 가지 옵션이 있음:

애드온으로 자동 (지속적 업데이트에 권장): POT 파일이 변경될 때마다 자동으로 msgmerge 를 실행하여 모든 PO 파일을 업데이트하는 PO 파일을 POT에 맞게 업데이트 (msgmerge) 애드온을 설치합니다.
업로드를 통해 수동: 원문 문자열 업데이트 가져오기 방법 를 사용하여 POT 파일을 업로드하면 기존 번역과 병합됩니다.

힌트

xgettext 또는 lupdate 와 같은 원문 문자열 추출 도구는 Weblate 외부에서 실행해야 합니다.

새 문자열 도입¶

문자열 관리 를 켜서 Weblate에서 새 문자열을 추가할 수 있지만, 일반적으로 새 문자열을 도입한 코드 변경과 함께 새 문자열을 도입하는 것이 낫습니다.

단일 언어 형식은 새 문자열이 단일언어 기반 언어 파일 에 추가되도록 구성해야 합니다. 일반적으로 코드를 작성하는 개발자가 수행합니다. 원문 문자열의 품질 관문 를 사용하여 해당 문자열의 검토 프로세스를 사용할 수 있습니다.

이중 언어 형식은 일반적으로 일부 도구 (xgettext 또는 intltool-update 등)를 사용하여 소스 코드에서 문자열을 추출합니다. 방법에 대한 지침은 현지화 프레임워크 문서를 따르세요. 문자열이 추출되면 기존 번역을 업데이트하기 위한 추가 단계가 필요할 수 있습니다 ( 대상 언어 파일 업데이트 참조).

힌트

문자열 추출 자동화는 현재 Weblate의 범위 밖입니다. 일반적으로 신뢰할 수 없는 코드를 실행해야 하므로 현지화 전용 플랫폼보다 일반적인 지속적 통합에 더 적합합니다.

새 문자열이 번역을 위해 자동으로 나타나도록 지속적 통합 파이프라인에 통합할 수 있습니다. 이러한 파이프라인은 병합 충돌 방지 도 다루어야 합니다.

로컬 VCS 저장소 관리¶

Weblate는 모든 번역을 기본 버전 관리 저장소에 저장합니다. 원격 저장소에 연결하는 것이 권장되지만 내부 전용 설정도 가능합니다. 저장소 유지보수 를 통해 이 저장소를 제어할 수 있습니다. 사용 가능한 작업에 대한 자세한 설명은 저장소 유지보수 를 참조하세요.

힌트

지속적 현지화 를 사용하면 모든 변경 사항이 저장소에서 자동으로 푸시되므로 일반적으로 수동으로 관리할 필요가 없습니다.