예제 코드 번역에 대한 논의 사항

[jaem0629]

번역 작업을 하다 보면 아래 이미지와 같이 예제 코드 중 주석만 번역된 경우도 있고, 텍스트까지 번역된 경우도 있습니다.
이의 경우 어떻게 하는 것이 올바른 것인가요?

주석만 번역된 경우

텍스트까지 번역된 경우

[hg-pyun]

음 모두 다 번역하면 좋겠지만, 원문 코드와 diff가 생겼을때 유지보수 비용과 트레이드 오프가 될 것 같기도하네요. 다른 분들 생각도 궁금합니다.

[jaem0629]

wiki의 universal-style-guide.md를 보면

주석을 제외한 모든 코드는 번역하지 않고 그대로 놔둬 주세요. 선택적으로 문자열에 있는 텍스트를 수정할 수 있지만, 코드를 참조하는 문자열은 번역하지 않도록 주의해주세요.

라고 되어 있네요. 개인적으로 코드 내부의 경우 주석만 번역하는 게 비교 또는 분석하기 좋다고 생각해요.

예를 들어 해당 글에서 코드 내부 텍스트 tasks를 작업으로 번역했다면, 위의 설명에서 tasks가 무엇인지를 고민 해야 할 수 있어요.

또한 코드를 직접 수정해 보며 분석할 때 변경점이 적을수록 원문 코드와 비교하기 편한 것 같아요.

[lumirlumir]

저는 주석까지만 번역하는게 옳은 방향인 것 같습니다. 주석은 실제 Code Sandbox 예제에 영향을 미치지 않으니까요.

[jaem0629]

저는 또한 아래와 같이 콘솔 로그를 인용하는 경우에도 번역하지 않는 것이 옳다고 생각해요. 실제 로그는 원문으로 나오니까요.

@lumirlumir 한국어로 번역된 코드 예제를 다시 원문으로 되돌리고 universal-style-guide.md를 아래와 같이 수정해도될까요?

주석을 제외한 모든 코드와 텍스트 및 콘솔 로그는 번역하지 않고 그대로 놔둬 주세요.

[nayounsang]

지금껏 의견을 정리하자면
주석만 번역할 것, 나머지를 번역하는 것은 원문과 싱크맞출 때 trade off

저도 동의합니다.
그리고 주석에 에러메시지가 포함된 경우가 있을까요? 그 경우도 영어 원문으로 남겨야할듯 싶네요.

[lumirlumir]

콘솔 로그를 인용하는 경우에도 번역하지 않는 것이 옳다고 생각해요. 실제 로그는 원문으로 나오니까요.

@jaem0629 네, 콘솔 메시지는 영어로 둬야 하는데 종종 확인을 못하고 넘어갈 때가 있네요ㅠㅠ

@lumirlumir 한국어로 번역된 코드 예제를 다시 원문으로 되돌리고 universal-style-guide.md를 아래와 같이 수정해도될까요?

이 부분은 기존에 번역된 부분들은 그냥 두고, 앞으로 새로 번역이 들어오는 부분과 충돌이 난 경우에만 영어 원문으로 넘어가는게 좋을 듯 합니다.

주석을 제외한 모든 코드와 텍스트 및 콘솔 로그는 번역하지 않고 그대로 놔둬 주세요.

이 부분을 문서에 추가하는건 좋은 의견인 것 같습니다!

---

그리고 주석에 에러메시지가 포함된 경우가 있을까요? 그 경우도 영어 원문으로 남겨야할듯 싶네요.

@nayounsang 이것도 좋은 의견 같아요. 이 부분은 케이스 바이 케이스라, 주석에 따라 직접 확인해보고 판단하면 될 듯 싶네요!

[jaem0629]

@lumirlumir 이미 번역된 예제를 다시 원문으로 되돌리는 작업은 당장 필요하지 않다고 느끼실 수 있지만, universal-style-guide.md 문서에 주석과 로그를 번역하지 말라는 내용을 추가한다면 결국 언젠가 가이드를 읽은 누군가가 번역된 예제를 다시 원문으로 되돌리려는 작업을 하게 될 거라고 생각해요. 따라서 문서의 일관성과 유지보수 측면에서 진행하는 것이 낫지 않을까요? 🤔

[nayounsang]

또한, 결정된 사항인 콘솔블럭 역시 자동화(린트)로 원문으로 남기게 할 수 있을듯 하네요. 된다면 리뷰 부담을 덜 수 있을 듯 한데요!

[lumirlumir]

@jaem0629 콘솔 메시지가 한국어로 잘못 표기된 부분에 대한 PR은 환영합니다. 다만, 스타일 가이드를 다시 참조해보니, 예제 코드 중 문자열에 있는 코드는 번역을 허용하기에, 이 부분은 PR 작성자에게 자유를 주는 편이 좋다 생각합니다.

ko.react.dev/wiki/universal-style-guide.md

Line 35 in c266e87

주석을 제외한 모든 코드는 번역하지 않고 그대로 놔둬 주세요. 선택적으로 문자열에 있는 텍스트를 수정할 수 있지만, 코드를 참조하는 문자열은 번역하지 않도록 주의해주세요.

@nayounsang 저는 추가적인 툴링을 추가하는 건 반대입니다. 현재 마크다운 및 자연어 처리를 위해 ESLint v7, ESLint v9, Textlint를 혼용하는 리포지토리의 특성 상, 추가적인 규칙들은 유지 보수가 힘들어집니다. 다만, 향후 업스트림인 react.dev가 ESLint v9 이상을 사용하고, Textlint를 ESLint v9과 통합했을때는 생각해볼만 하기에, react.dev 리포지토리에 ESLint v9 마이그레이션 PR을 먼저 보내 보는게 좋을 것 같아요

[jaem0629]

@lumirlumir 저는 "선택적으로 번역 가능"이라는 기존 가이드가 자유보다 오히려 혼란을 줄 수 있다고 생각해요. 선택적이라고 하면 PR마다 기준이 달라지고, 같은 문서 안에서도 어떤 예제는 한국어, 어떤 예제는 영어인 상황이 생길 수도 있어요.

또한 제가 위에서 언급했던 tasks 예시처럼, 코드 상의 문자열을 "작업"으로 번역했지만 본문에선 tasks로 설명하는 상황이 발생하면 "작업"이 무슨 의미인지 추측해야 해서 가독성이 떨어지게 되어요.

기여자 입장에서도 번역해도 되는지를 고민하는 것보다, "주석을 제외한 문자열은 번역 안 함"으로 기준이 잡혀있다면 명쾌할 것 같고요.

그래서 저는 기존 가이드 수정을 제안드려요. 물론 trade-off가 있고 자유도가 주는 이점이 더 크다고 판단하신다면 따르겠습니다!

[lumirlumir]

또한 제가 위에서 언급했던 tasks 예시처럼, 코드 상의 문자열을 "작업"으로 번역했지만 본문에선 tasks로 설명하는 상황이 발생하면 "작업"이 무슨 의미인지 추측해야 해서 가독성이 떨어지게 되어요.

이런 부분이 있다면 이슈를 올려주시거나 PR을 보내주세요. 기여는 언제나 환영입니다.

다만, "가이드"는 언제나 Best Practice를 권장하는 하나의 기준선일 뿐, 이를 강제할 수는 없습니다. 외부 기여 위주로 운영되는 프로젝트의 특성 상, 수백명의 모든 기여자가 문서의 미묘한 일관성을 유지하는 것도 불가능할 뿐더러, 이를 강제하려면 필수적으로 "문서"가 아닌 "코드"형태로 작성되어져, CI/CD에 통합되어야 합니다. 하지만, 앞서 언급했듯 자연어 처리의 특성, 그리고 Legacy 의존성에 대한 관리가 안되는 react.dev의 특성 상, 한국 공식 문서에만 추가적인 코드 혹은 린트 규칙들을 작성하게 되면 추후 유지 보수가 어려워 집니다. 이는 작은 일관성 개선을 위한 불필요한 오버헤드라고 생각합니다.

혹시나 해서 말씀드리지만, 한국 React 문서의 메인테이너 및 기여자 분들은 모두 개인 자유시간을 할애해 봉사 개념으로 프로젝트의 운영을 돕고 있습니다. 그렇기에 저희는 반드시 필요한 부분이 아니라면, 유지 보수 비용이 최대한 적게 드는 방향으로 기준점을 잡고 움직입니다.

만약, 이러한 부분에 대한 CI/CD 통합 및 개선을 원하신다면, react.dev 리포지토리에 먼저 ESLint v9에 대한 마이그레이션 PR을 작성해서 저희가 추후에 받아올 수 있게 해주세요. 현재 Textlint가 제공하는 API는 앞서 언급해주신 규칙들을 강제하기에는 기술적인 제약들이 많습니다.

---

TL;DR 이번 이슈에 대한 해결 범위는 아래 내용을 문서에 추가하는 것으로 제한합니다.

• 콘솔 로그는 번역하지 않고 그대로 놔둬 주세요.
• 코드 샌드박스 주석에 에러 메시지가 포함된 경우에는 영어 원문으로 남겨주세요.