Weblate 구성 요소에 대해 알아보자!

sookju · 10월 7, 2025, 9:04오전

Weblate란?

Weblate란 오픈소스 웹 기반 번역 관리 시스템입니다. 가장 큰 장점 중 하나는 번역 및 시스템 관리에 필요한 기능에 대해 사용자 맞춤 설정을 지원한다는 점입니다. 호스팅 방식, 버전 관리 시스템, 자동화된 워크플로우 설정 등 사용자의 요구사항에 따라 적절하게 설정할 수 있습니다.

Weblate 구성 요소

Weblate는 크게 4가지 구성으로 이뤄져있습니다.

프로젝트(Project): 최상단의 프로젝트 관리 단위로 번역할 프로젝트를 의미합니다.
카테고리(Category)(Optional): 여러개의 컴포넌트를 하나로 묶어서 관리할 수 있는 분류 단위입니다.
컴포넌트(Component): 번역(Translation) 파일의 모음으로 주로 번역 대상을 지정하고 번역 파일 위치, 포맷 등에 대한 설정을 수행합니다.
번역(Translation): 번역 작업의 단위입니다. 실제로 사용자는 번역을 통해 번역 작업을 수행하게 됩니다.

Tip!: Weblate 구성 요소 = 번역 파일 저장 경로

저는 Weblate Migration을 수행하면서 번역 파일 경로와 관련해서 많은 시행착오를 겪었습니다. 이 과정을 통해 제가 드릴 수 있는 팁은 번역 파일 저장 경로를 기준으로 Weblate 구성을 설계하는 것입니다.

Weblate는 기본적으로 프로젝트/컴포넌트 트리 구조 형식으로 번역 파일을 관리합니다. 즉, 프로젝트, 컴포넌트 구성만으로 번역 파일 경로가 정의됩니다.

예로 Horizon 프로젝트의 releasenotes 번역을 일반적인 번역 파일 포맷인 PO 형식으로 로컬 레포지토리 내 /LC_MESSAGES/*/example.po 경로로 저장한다고 가정해봅시다.

이를 폴더 구조로 정의했을때 아래와 같이 설정할 수 있습니다.

|- Horizon
	|- releasenotes
		|- LC_MESSAGES
			|- ko_KR
				|- example.po
			|- en_US
				|- example.po

이를 Weblate 구성 요소로 대입하면 아래와 같습니다.

|- Horizon -> Project
	|- releasenotes -> Component
		|- LC_MESSAGES
			|- ko_KR
				|- example.po -> Translation
			|- en_US
				|- example.po -> Translation

카테고리를 추가할 경우 아래와 같은 폴더 구조로 구성할 수 있습니다.

|- Horizon -> Project
	|- current -> Category
		|- releasenotes -> Component
			|- LC_MESSAGES
				|- ko_KR
					|- example.po -> Translation
				|- en_US
					|- example.po -> Translation
	|- legacy -> Category
		|- releasenotes -> Component
			|- LC_MESSAGES
				|- ko_KR
					|- example.po -> Translation
				|- en_US
					|- example.po -> Translation

프로젝트(Project)

프로젝트는 최상단의 프로젝트 관리 단위로 번역할 프로젝트를 의미합니다.

속성

project name: 프로젝트 이름
url slug: URL에 나타낼 프로젝트 slug
project website: 프로젝트에 대한 URL

실습

weblate의 projects 탭에서 + Project 를 통해 바로 프로젝트를 생성할 수 있습니다.

카테고리(Category)

카테고리는 여러개의 컴포넌트를 하나로 묶어서 관리할 수 있는 분류 단위입니다. 필수는 아닙니다.

속성

category name: 카테고리 이름
category slug: URL에 표시될 slug 이름

실습

프로젝트에서 Operations>Add new category에 들어가면 새로운 카테고리를 생성할 수 있습니다.

프로젝트와 마찬가지로 카테고리도 slug를 요구합니다. 실제로 웹사이트 URL은 지정한 slug로 중첩되어 나타냅니다.

컴포넌트(Component)

컴포넌트는 번역(Translation)의 모음으로 주로 번역 대상을 지정하고 번역 파일 위치, 포맷 등에 대한 설정을 수행합니다. 번역 관리 시스템을 설정하는데 있어 가장 중요한 구성 요소입니다.

Weblate는 번역 파일을 관리하는 시스템으로 아래의 요소들을 정의해야 합니다.

어떤 원본을 기준으로 번역본이 만들어지지?
어떤 형식으로 저장되지? ex) po, json …
어떻게 저장되지? ex) 원격, 로컬
어떤 경로로 번역 파일이 저장되지?
원본은 무슨 언어일까?

속성

중요하다고 생각하는 속성만 작성했습니다.

file_format: 파일 형식
repository: 번역 파일이 저장될 레포지토리. 로컬인 경우 서버의 FileSystem에 저장됨.
filemask: 번역 파일 검색 및 배치 규칙을 정의하는 기준
new_base: 신규 언어 번역 추가 시 기준이 되는 원본 파일 위치 또는 경로
source_language: 원본 파일의 언어

실습

카테고리를 추가하지 않는 경우 Component 탭에서 쉽게 추가할 수 있습니다.

반면, 카테고리가 있는 경우에는 Operations>Add new translation component 탭에서 추가할 수 있습니다.

저는 아래와 같은 예시로 컴포넌트를 생성해보겠습니다.

어떤 원본을 기준으로 번역본이 만들어지지? → django.pot
어떤 형식으로 저장되지? → po
어떻게 저장되지? → local
어떤 경로로 번역 파일이 저장되지? → locale/*/LC_MESSAGES/django.po
원본은 무슨 언어일까? → en_US

django.pot를 zip으로 압축합니다. 해당 파일은 압축해제되어 컴포넌트 폴더에 바로 저장됩니다.

VCS는 로컬 레포지토리(local:)로 설정했습니다.

파일 포맷은 po 형식으로 설정했습니다.

file format	description
po	원본과 번역 문자열을 하나의 파일에서 관리
po-mono	원본과 번역 문자열을 따로 관리

번역 파일이 저장될 위치(file maask)를 locale/*/LC_MESSAGES/django.po 형태로 저장했습니다. 이때 *는 언어를 의미하며, 한글 번역을 수행할 경우 locale/ko_KR/LC_MESSAGES/django.po로 저장됩니다.

template를 이전에 업로드한 django.pot로 지정하여 원본 파일을 지정합니다. 추후 원본 파일이 변경되면, template를 교체하시면 됩니다.

file format의 종류에 따라 필수 속성이 있습니다. 공식 문서를 참고하시길 바랍니다.

원본 언어셋인 en_US의 개요를 확인한 결과 repository, filemask, translation file(template) 이 적절하게 설정되었음을 확인할 수 있습니다.

번역(Translation)

번역 작업의 단위입니다. 실제로 사용자는 번역(Translation)을 통해 번역 작업을 수행하게 됩니다.

번역의 언어셋은 Weblate 서버의 Language를 기준으로 설정됩니다. 만약에 사용자가 커스텀 언어셋을 추가하고 싶다면, Languages 탭에서 추가하시길 바랍니다.

앞서 컴포넌트에서 원본 파일을 지정한다고 말씀드렸습니다. 만약에 사용자가 한국 번역을 수행하고 싶다면 Weblate를 통해 컴포넌트의 원본 파일 기준으로 번역 파일을 생성하게 됩니다.

ko_KR 번역을 추가한 후 번역해보겠습니다.

웹상에서 번역을 마친 후 번역 파일을 다운로드 받아보겠습니다.

앞서 말했듯이 프로젝트/카테고리/컴포넌트의 설정대로 폴더가 구성되어 있습니다.

po 파일을 확인한 결과 정상적으로 번역되었습니다.

# Translations template for zun-ui.
# Copyright (C) 2025 ORGANIZATION
# This file is distributed under the same license as the zun-ui project.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2025.
#
msgid ""
msgstr ""
"Project-Id-Version: zun-ui VERSION\n"
"Report-Msgid-Bugs-To: https://bugs.launchpad.net/openstack-i18n/\n"
"POT-Creation-Date: 2025-10-05 15:14+0900\n"
"PO-Revision-Date: 2025-10-07 08:31+0000\n"
"Last-Translator: Weblate Admin <weblate.admin@example.com>\n"
"Language-Team: Korean (South Korea) <http://skj.printf.kr/projects/"
"openinfra-kr/master/django/ko_KR/>\n"
"Language: ko_KR\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"
"X-Generator: Weblate 5.13\n"
"Generated-By: Babel 2.17.0\n"

#: zun_ui/content/container/capsules/panel.py:18
#: zun_ui/content/container/capsules/urls.py:17
msgid "Capsules"
msgstr ""

#: zun_ui/content/container/containers/admin_urls.py:18
#: zun_ui/content/container/containers/panel.py:22
#: zun_ui/content/container/containers/panel.py:27
#: zun_ui/content/container/containers/urls.py:18
msgid "Containers"
msgstr "컨테이너들"

마치며

지금까지 Weblate 소개와 구성 요소에 대해 간략하게 설명했습니다.
Weblate는 다양한 맞춤형 설정이 가능해 조직의 요구사항에 따라 구성 요소의 설정값이 다를 수 있습니다. 그래서 때에 따라 속성값을 선별하고 적용하는 과정이 필요합니다.

현재 저희 팀은 Zanata에서 Weblate으로 번역 관리 시스템을 이관하는 작업을 수행하고 있습니다. 그 중 저는 Zanata에 있는 번역 파일을 Weblate로 이관하는 담당을 맡았습니다.

다음 글에서는 이번에 설명한 개념을 구체화해서 어떻게 Zanata에 있는 번역 파일을 Weblate로 이관했는지 설명해보겠습니다.

Reference

Weblate Documentation