DEVOCEAN

Apache Airflow가 3.0 버전으로 올라가면서, 기존의 FAB(Flask App Builder) 기반 UI에서 React 기반 UI로 전면 개편되었습니다.

이 과정에서 여러 흥미로운 기능들이 추가되었는데요,

이번 글에서는 그 중 하나인 i18n 기능과, 한국어 번역 기여 가이드에 대해 소개해드리겠습니다.

i18n 프로젝트란?

Airflow의 i18n(Internationalization) 프로젝트는 Airflow의 웹 UI를 다양한 언어로 번역할 수 있도록 국제화를 지원하는 작업입니다.

이 프로젝트는 문자열을 모국어로 변경하는 것 이상으로, 다음과 같은 목표를 가지고 있습니다:

• 사용자 경험 향상: 모국어 UI 제공으로 접근성 향상

• 글로벌 커뮤니티 활성화: 다양한 언어권 기여자들의 참여 유도

• 번역 품질 유지: 일관된 용어와 구조를 유지해 지속 가능성 확보

현재 Airflow는 영어를 기본 언어(default locale)로 사용하며, 각 언어별 JSON 파일을 통해 다양한 locale을 지원하고 있습니다.

한국어도 공식적으로 지원되는 locale 중 하나이며, 지속적인 기여가 필요한 상황입니다.

로컬 환경 구축하기

Airflow의 UI 번역에 기여하려면 로컬 환경에서 번역 파일을 수정하고, 실제 UI에서 어떻게 보이는지 테스트해볼 수 있어야 합니다.

이를 위해 Airflow에서는 공식 개발 툴인 Breeze를 사용합니다.

저장소 클론

git clone https://github.com/apache/airflow.git
cd airflow

Airflow Breeze 세팅 & 실행

1. Breeze 세팅

uv tool install -e dev\breeze

Breeze는 Docker Compose 기반으로 작동하므로, 사용 전에 Docker 환경이 실행 중이어야 합니다.

2. Breeze 실행

breeze --python 3.10 --backend postgres start-airflow --dev-mode

• Python은 3.10

• backend는 postgres

• --dev-mode 옵션을 통해 코드 수정을 핫 로드 가능하도록 합니다.

※ 위 옵션들은 필요에 따라 수정 가능합니다.

명령어를 실행하면 아래와 같이 나올 것입니다.

그럼 http://localhost:28080 으로 Airflow UI에 들어가서 admin, admin으로 로그인 해줍니다.

좌측 하단의 User > Select Language 를 통해 UI를 한국어로 변경할 수 있습니다.

그럼 이제 번역 기여 방법에 대해서 알아봅시다.

한국어 번역 기여방법

Airflow의 번역은 단순히 "PR을 열고 번역을 올린다"는 것만으로 끝나지 않습니다.

공식 정책에 따라 책임자, 승인자, 검수 절차 등이 세분화되어 있어, 기여 전에 몇 가지 구조를 이해해두면 좋습니다.

번역 파일 구조 이해

Airflow UI 한국어 번역 파일은 다음 경로에 위치합니다:

airflow-core/src/airflow/ui/public/i18n/locales/ko/*.json

여기에 각 UI 텍스트에 해당하는 key-value 형태의 JSON이 있으며, "value" 부분을 번역하는 것이 저희의 역할입니다.

{
  "columns": {
    "description": "설명",
    "key": "키",
    "name": "이름",
    "value": "값"
  },
}

만약 새로운 UI 문자열이 추가되면, 한국어 번역 파일에도 해당 키가 추가 되며, TODO: translate: 로 표시되어, 번역이 필요한 항목을 쉽게 찾을 수 있습니다:

    "nothingFound": {
      "description": "TODO: translate: Connections defined via environment variables or secrets managers are not listed here.",
      "documentationLink": "TODO: translate: Learn more in the Airflow documentation.",
      "learnMore": "TODO: translate: These are resolved at runtime and are not visible in the UI.",
      "title": "연결을 찾을 수 없습니다."
    },

이러한 항목들을 찾아 번역하고 PR을 보내는 것이 가장 기본적인 기여 방법입니다.

번역 기여 툴 사용법 & 몇 가지 팁

Airflow에 누락된 번역을 자동으로 검사하고, TODO 항목을 추가해주는 도구가 있습니다.

uv run dev/i18n/check_translations_completeness.py --language ko --add-missing

이 명령어를 실행하면 아래와 같은 결과가 출력됩니다:

각 파일별로 어떤 항목이 누락되었는지, 파일별 번역 진행률이 얼마인지도 확인할 수 있습니다.

이 명령어를 통해 TODO: translate: 를 생성할 수 있으니, 새로운 UI 문자열이 추가되면 해당 명령어를 실행해주어야합니다.

그리고 번역을 하면서 몇 가지 팁이 있자면:

• Breeze 환경에서 직접 UI를 띄워 번역이 어떻게 반영되는지 테스트해보세요.

• 영어를 직역하기보다는 자연스럽고 사용자 친화적인 표현이 중요합니다.

• {variable}이나 %s 등 형식 요소는 반드시 그대로 유지해주세요.

PR 작성 방법

• 한 PR에서 너무 많은 항목을 다루기보다는, 관련한 항목끼리 묶어서 올리는 것이 좋습니다.

• 가능하면 기존에 번역보다 TODO: 로 표시된 항목을 번역하는 것이 우선입니다.

• PR 설명에는 어떤 항목들을 번역했는지 간략하게 명시하면 좋습니다.

• 번역시 일관된 용어 사용을 위해 기존 번역 예시를 참고해주세요.

PR 승인 절차

Airflow의 i18n 정책에 따르면, 모든 번역 PR은 다음 조건을 충족해야합니다.

• 해당 언어의 Translation Owner가 언어적 측면을 승인해야 합니다.

• Code Owner 또는 커미터가 기술적 측면(포맷, 린트 등)을 확인하고 병합합니다.

현재 한국어 번역의 경우, Airflow 한국 사용자 모임에서 품질 검토를 담당하고 있습니다.

Airflow 한국사용자 모임에서 검토를 맡고 계신 분들은

저 @choo121600 와 김건우 님 @kgw7401, 양원석 님 @0ne-stone께서 담당하고 계십니다.

따라서 PR을 하실 때, 아래와 같이 저희를 태그해서 진행해주시면 더욱 빠른 리뷰에 도움이 됩니다!

예시 PR:

https://github.com/apache/airflow/pull/52440

마치며

번역은 기여를 시작하는 데 가장 부담이 적은 방법 중 하나입니다.

하지만 단순한 작업 그 이상으로, Airflow의 기여 방식과 문화를 체험하는 가장 좋은 기회이기도 합니다.

처음엔 작은 오타 하나, 하나의 문장을 자연스럽게 고치는 것부터 시작해보세요.

(제가 작업한 번역에도 어색한 부분이 아직 좀 있습니다. 편하게 제안주세요.)

혹시 기여를 하고 싶은데 어려움이 있다면,

이 게시글 댓글을 통해 언제든지 편하게 질문해주세요!