Apache Airflow i18n 한국어 번역 기여 참여 가이드

정보공유
,
1

지난 Airflow 3회 밋업에서 Airflow i18n 프로젝트의 한국어 지원 현황과 함께, 한국어 번역에 어떻게 기여할 수 있는지를 간단히 소개드렸었는데요.

시간 관계상 자세히 말씀드리지 못했던 내용을 이 글을 통해 보완하고자 합니다.

i18n 프로젝트란?

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

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

  • 사용자 경험 향상: 모국어 UI 제공으로 접근성 향상
  • 글로벌 커뮤니티 활성화: 다양한 언어권 기여자들의 참여 유도
  • 번역 품질 유지: 일관된 용어와 구조를 유지해 지속 가능성 확보

현재 Airflow는 영어를 기본 언어(default locale)로 사용하며, 각 언어별 JSON 파일을 통해 다양한 locale을 지원하고 있습니다.
한국어도 공식적으로 지원되는 locale 중 하나이며, 지속적인 기여가 필요한 상황입니다.

한국어 번역 기여방법

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

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

image
image827×670 47.9 KB

각 파일별로 어떤 항목이 누락되었는지, 파일별 번역 진행률이 얼마인지도 확인할 수 있습니다.
이 명령어를 통해 TODO: translate: 를 생성할 수 있으니, 새로운 UI 문자열이 추가되면 해당 명령어를 실행해주어야합니다.

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

  • Breeze 환경에서 직접 UI를 띄워 번역이 어떻게 반영되는지 테스트해보세요.
  • 영어를 직역하기보다는 자연스럽고 사용자 친화적인 표현이 중요합니다.
  • {variable}이나 %s 등 형식 요소는 반드시 그대로 유지해주세요.

PR 작성 방법

  • 한 PR에서 너무 많은 항목을 다루기보다는, 관련한 항목끼리 묶어서 올리는 것이 좋습니다.
  • 가능하면 기존에 번역보다 TODO: 로 표시된 항목을 번역하는 것이 우선입니다.
  • PR 설명에는 어떤 항목들을 번역했는지 간략하게 명시하면 좋습니다.
  • 번역시 일관된 용어 사용을 위해 기존 번역 예시를 참고해주세요.

PR 승인 절차

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

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

현재 한국어 번역의 경우, 한국 사용자 모임에서 품질 검토를 담당하고 있습니다.
한국사용자 모임에서 검토를 맡고 계신 분들은
저 @choo121600 와 김건우 님 @kgw7401, 양원석 님 @0ne-stone께서 담당하고 계십니다.

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

image
image1832×1527 341 KB

예시 PR:

마치며

저는 Airflow의 한국어 지원은 단순한 번역 이상이라고 생각합니다.
한국어로 번역됨으로써 더 많은 사람들이 Airflow에 대해 쉽게 접근할 수 있게 되며,
이는 저희 커뮤니티의 성장에도 도움이 된다고 생각합니다.

번역은 기여를 시작하는 데 가장 부담이 적은 방법 중 하나입니다.
하지만 단순한 작업 그 이상으로, Airflow의 기여 방식과 문화를 체험하는 가장 좋은 기회이기도 합니다.

혹시 기여를 하고 싶은데 어려움이 있다면,
저희 포럼 질의응답 채널이나 이 게시글 댓글을 통해 언제든지 편하게 질문해주세요!

1개의 좋아요