첫 번째 Gitea 기여(DNF5 명령어 수정)를 마치고 나니, 다음 기여거리를 찾는 데 훨씬 자신감이 붙었습니다. 이번에는 영문 로케일 파일의 오타와 문법 오류를 수정하고, Go 소스코드의 키 참조까지 함께 고친 과정을 공유합니다.
Table of Contents
배경: 이슈를 찾기까지
Gitea 프로젝트에 기여할 이슈를 찾던 중, 핵심 메인테이너가 직접 작성한 메타 이슈 #35015를 발견했습니다. "Some good first issues (likely easy to fix) for contributors"라는 제목의 이 이슈에는 여러 기여 방향이 제시되어 있었는데, 그중 첫 번째가 바로 영문 로케일 개선이었습니다.
Many contributors are not English native speakers (include me), so some sentences don't read good
메인테이너 본인도 영어 원어민이 아니라서, 어색한 표현이 많다는 것이었습니다. good first issue 라벨이 달려 있고, 메인테이너가 직접 방향을 제시한 이슈라 기여하기에 안성맞춤이었습니다. 첫 번째 기여 때 로케일 시스템의 구조를 이미 파악해둔 것도 한몫했습니다.
분석 과정
로케일 파일 구조 파악
가장 먼저 로케일 파일의 위치와 형식을 확인했습니다. Gitea는 과거에 .ini 형식을 사용했지만, 최신 코드에서는 JSON으로 전환된 상태였습니다.
options/locale/locale_en-US.json # 약 3,749줄Code language: PHP (php)다른 언어의 번역 파일도 같은 디렉토리에 있지만, Gitea는 Crowdin으로 번역을 관리하기 때문에 영문 파일만 수정하면 나머지 언어는 자동으로 동기화됩니다. 이 점을 사전에 파악한 덕분에 불필요한 파일 수정을 피할 수 있었습니다.
grep으로 문제 찾기
먼저 grep으로 오타를 체계적으로 검색했습니다.
# 의심되는 오타 검색
grep -n "enterred" options/locale/locale_en-US.jsonCode language: PHP (php)581: "form.enterred_invalid_password": "..."
582: "form.enterred_invalid_email": "..."
583: "form.enterred_invalid_name": "..."
584: "form.enterred_invalid_url": "..."Code language: JavaScript (javascript)entered를 enterred로 잘못 쓴 오타가 4건이나 있었습니다. 추가로 문법 오류도 발견했습니다.
grep -n "enables your\|gives your" options/locale/locale_en-US.jsonCode language: JavaScript (javascript)874: "oauth2_applications_desc": "... applications enables your ..."
893: "oauth2_application_create_description": "... applications gives your ..."Code language: JavaScript (javascript)주어가 복수(applications)인데 동사에 3인칭 단수 -s가 붙어 있는 주어-동사 불일치 오류였습니다.
마지막으로, 어색한 표현도 하나 발견했습니다.
"startpage.license_desc": "Don't be shy to be a contributor!"Code language: JavaScript (javascript)"Don't be shy to be a contributor"는 영어로 부자연스럽습니다. "Don't hesitate to contribute"가 훨씬 자연스럽습니다.
키 이름 변경의 파급 효과 확인
단순한 텍스트 수정이라면 JSON 파일만 고치면 되지만, enterred → entered는 키 이름 자체를 바꾸는 작업이었습니다. 키 이름은 Go 소스코드에서 직접 참조하기 때문에, 참조하는 곳을 모두 함께 수정해야 합니다.
# Go 코드에서 키 참조 위치 확인
grep -rn "enterred" --include="*.go" .Code language: PHP (php)routers/web/org/setting.go # 2곳
routers/web/user/setting/account.go # 1곳
routers/web/repo/setting/setting.go # 7곳Code language: PHP (php)총 3개 Go 파일, 10곳에서 이 키를 참조하고 있었습니다. 첫 번째 기여 때 배운 교훈이 여기서도 적용되었습니다 — 키 이름 변경은 반드시 소스코드까지 함께 확인해야 합니다.
해결: 수정 작업
브랜치 생성과 수정
# 작업 브랜치 생성
git checkout -b fix/locale-en-us-typos
# 1. Go 코드의 키 참조 수정 (enterred → entered)
sed -i '' 's/form\.enterred_invalid/form.entered_invalid/g' \
routers/web/org/setting.go \
routers/web/user/setting/account.go \
routers/web/repo/setting/setting.go
# 2. JSON 로케일 파일의 키 이름 수정
sed -i '' 's/form\.enterred_invalid/form.entered_invalid/g' \
options/locale/locale_en-US.json
# 3. 주어-동사 일치 수정
sed -i '' 's/applications enables your/applications enable your/' \
options/locale/locale_en-US.json
sed -i '' 's/applications gives your/applications give your/' \
options/locale/locale_en-US.json
# 4. 어색한 표현 개선
sed -i '' "s/Don't be shy to be a contributor\!/Don't hesitate to contribute\!/" \
options/locale/locale_en-US.jsonCode language: PHP (php)커밋과 PR 생성
Gitea는 DCO(Developer Certificate of Origin)를 요구하므로 -s 플래그로 서명을 추가합니다.
git commit -s -m "Fix typos and grammar in English locale and related Go code
- Rename \"enterred\" to \"entered\" in locale keys and Go source files
- Fix subject-verb agreement: \"enables\" -> \"enable\", \"gives\" -> \"give\"
- Improve awkward phrasing: \"Don't be shy to be a contributor\" -> \"Don't hesitate to contribute\"
Ref #35015"Code language: PHP (php)PR 본문에서는 Fixes 대신 Ref #35015를 사용했습니다. #35015는 여러 작업을 포함하는 메타 이슈이기 때문에, 이 PR 하나로 이슈가 닫히면 안 되기 때문입니다.
결과: PR 제출 후
PR #36751을 올린 후 CI에서 run failed가 표시되었습니다. 처음에는 코드 문제인가 걱정했지만, 실제 원인은 pnpm/action-setup@v4 설치 실패였습니다. 즉 GitHub Actions 인프라 문제로, 코드와는 전혀 무관했습니다.
GiteaBot이 자동으로 lgtm/need 2 (메인테이너 2명의 승인 필요) 라벨과 modifies/go 라벨을 붙여주었습니다.
추가로 알아두면 좋은 점
Gitea의 로케일 시스템에서 고유명사(Fedora, DNF5 등)는 번역 대상이 아닙니다. 이런 이름이 locale 키의 값에 들어 있다면 그대로 하드코딩해야 하며, 번역 시스템을 통해 변환되면 안 됩니다. 이 교훈은 첫 번째 기여의 코드 리뷰에서 배운 것이기도 합니다. [💡 보완]
키 이름을 변경할 때는 반드시 grep -rn으로 모든 참조 위치를 확인해야 합니다. Go 코드뿐 아니라 템플릿 파일(.tmpl)에서도 키를 사용할 수 있으므로, --include 옵션으로 파일 형식을 확장해서 검색하는 것이 안전합니다. [💡 보완]
macOS에서 sed -i를 사용할 때는 sed -i ''처럼 빈 문자열 인자를 줘야 합니다. GNU sed와 BSD sed의 문법 차이 때문입니다. [💡 보완]
마무리
핵심을 정리하면 이렇습니다:
- 메인테이너가 직접 작성한 메타 이슈는 최적의 진입점이다 -
good first issue라벨 + 구체적 방향 제시가 있으면 바로 시작할 수 있습니다 - 키 이름 변경은 소스코드 참조까지 반드시 함께 수정해야 한다 -
grep -rn으로 모든 참조를 찾는 습관이 중요합니다 - CI 실패는 당황하지 말고 원인부터 확인하라 - 인프라 문제인지 코드 문제인지 먼저 구분하세요
첫 번째 기여에서 프로젝트 구조와 기여 프로세스를 익힌 덕분에, 두 번째 기여는 훨씬 수월했습니다. 한 프로젝트에 반복 기여하면 컨텍스트가 쌓여서 점점 효율적이 됩니다.
관련 링크:
조회수: 0