Apache Airflow i18n 한국어 번역 기여 온라인 워크샵

[choo121600]

Airflow 3.1 릴리스부터 드디어 한국어(ko)가 공식 지원되었습니다.
이제 누구나 쉽게 Airflow UI를 한국어로 사용하고 이에 기여할 수 있게 되었습니다.

기존에 공유드렸던 Apache Airflow i18n 한국어 번역 기여 참여 가이드라는 글이 있지만, 최근 아래의 PR이 병합되면서 번역 기여 방식이 일부 변경되었습니다.

Convert `check_translation_completeness.py` into breeze command

그래서 변경된 내용을 반영하여 업데이트 버전의 한국어 번역 기여 가이드를 공유드리는 온라인 워크샵을 준비했습니다!

슬라이드:

Airflow 한국어 번역 워크샵 v1

우리가 기여한 것이 어떻게 보여지나요?

PR이 머지되면 아래 화면처럼 번역이 Airflow UI에 바로 적용됩니다.

i18n 프로젝트가 뭔가요?

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

단순 번역이 아니라, 아래 가치를 중심으로 운영됩니다:

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

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

한국어 번역 기여 참여 방법

Airflow의 i18n은 단순히 JSON을 수정하는 작업이 아니라, 정해진 정책과 툴을 활용하는 정식 기여 프로세스를 따릅니다.
아래 단계를 따라하면 누구나 쉽게 첫 PR을 만들 수 있습니다.

Airflow 레포지토리 포크

• 브라우저에서 Apache Airflow 레포지토리로 이동
• 우측 상단 Fork 버튼 클릭
• 내 GitHub 계정으로 복사됩니다.
• 복사된 저장소 URL을 확인
  • 예: https://github.com/<내 계정>/airflow.git

로컬에 클론

git clone https://github.com/<내 계정>/airflow.git
cd airflow

<내 계정> 부분을 자신의 GitHub 사용자명으로 바꾸세요.

개발 환경 준비

개발 환경 준비가 필요하다면 Breeze를 사용하는 것을 추천합니다:

uv pip install -e ./dev/breeze

작업용 브랜치 생성

git checkout -b i18n/workshop

브랜치 이름은 작업 내용과 관련 있게 작성하시면됩니다.

번역 파일 구조

번역을 하실 때 참고할 영어 원본 파일은:
airflow-core/src/airflow/ui/public/i18n/locales/en 폴더 안에 있어요.

한국어 번역 파일은:
airflow-core/src/airflow/ui/public/i18n/locales/ko 폴더 안에 있습니다.

예를 들어, columns 관련 JSON은 이렇게 되어 있습니다:

{
  "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": "연결을 찾을 수 없습니다."
}

번역 기여 툴 사용법 Airflow Breeze

번역 완료 여부 확인

breeze ui check-translation-completeness --language ko

• Missing: 누락된 번역
• Extra: 불필요한 번역
• TODOs: TODO로 추가되었지만 아직 완료되지 않은 번역

누락 항목 자동 추가

breeze ui check-translation-completeness --language ko --add-missing

• TODO: translate 형식으로 추가됩니다.

불필요한 번역 제거

breeze ui check-translation-completeness --language ko --remove-extra

번역 내용 확인

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

브라우저에서 localhost:28080 접속 후 admin/admin 로그인으로 확인 가능합니다.

• Breeze 환경에서 UI를 띄워 번역이 실제로 어떻게 반영되는지 확인하세요.
• {variable} 또는 %s 같은 형식 요소는 그대로 유지해야 합니다.
• 영어 직역보다는 자연스럽고 사용자 친화적인 표현을 추천합니다.

PR 작성 방법

• 한 PR에 너무 많은 항목을 넣기보다, 관련 항목끼리 묶어 올리세요.
• 기존 TODO: 항목 번역을 우선합니다.
• PR 설명에는 번역한 항목을 간략하게 명시하세요.
• 기존 번역 예시를 참고하여 용어 일관성을 유지합니다.

PR 제목 예시

i18n(Ko): add missing translations (Nov 19)

예시 PR

i18n(Ko): add missing translations in assets.json (Nov 26)

PR 승인 절차

Airflow i18n 정책에 따라 모든 번역 PR은 아래 조건을 충족해야 합니다:

• Translation Owner가 언어적 측면 승인
• Code Owner 또는 커미터가 기술적 측면(포맷, 린트 등) 확인 후 병합

한국어 번역의 경우, 한국 사용자 모임에서 품질 검토를 담당하고 있습니다.
검토 담당자: @choo121600, @kgw7401, @onestn
PR 작성 시 이분들을 태그하면 리뷰가 빠릅니다.

마치며

번역 기여는 Airflow의 기여 방식과 문화를 경험할 수 있는 가장 좋은 기회입니다.
한국어 번역에 어려움이 있으면, 포럼 질의응답 채널이나 이 글의 댓글을 통해 질문해주세요.

[choo121600]