2026 년 7 월 10 일

• Markdown -> JSONL Converter로 공식문서 JSONL 변환 수집량을 1180개에서 1230개까지 진행함
• 다국어 번역 파이프라인이 생각보다 많이 지연되어, 안정화까지 시간이 오래 걸릴 수 있다는 점을 확인했다.
• private 레포에서 다국어 문서 동기화 파이프라인을 테스트했고, 그 과정에서 내가 세운 기준은 다음과 같다.

문서 구조 기준:

• 한국어 문서를 기준 문서로 둔다.
• 다국어 문서는 docs/<lang>/... 형태로 둔다.
• 기존에 docs/ 바로 아래에 있던 하위 경로는 한국어 기준 문서로 보고 docs/ko/... 아래로 옮긴다.
• 언어 코드는 jp, ch 같은 임의 코드가 아니라 ja, zh, pt-BR처럼 표준 언어 코드를 사용한다.
• 루트 README.md는 루트 문서로 유지한다.
• README 번역본도 루트 기준으로 처리한다.
• README.md 수정이 docs/ 안 파일 수정으로 잘못 이어지지 않게 한다.
• 이미 존재하는 docs/en, docs/ja 같은 언어 폴더가 docs/ko/en처럼 중첩되지 않게 한다.
• 압축파일 테스트 시에는 README와 docs만 풀어서 반영한다.

링크와 경로 기준:

• README와 docs 내부 링크는 대상 언어에 맞게 바꾼다. 예를 들어 한국어 README의 docs/ko/... 링크는 영어 README에서 docs/en/...로 바꾼다.
• docs 내부 문서끼리 연결되는 상대 경로도 대상 언어 기준으로 바꾼다.
• 이미지 경로, 하위 디렉토리 링크, 상대 경로가 번역/동기화 과정에서 깨지지 않게 한다.
• README의 언어 링크는 사용자가 해당 언어 문서로 이동하거나 전환된다고 느낄 수 있는 형태로 둔다.

자동 동기화 기준:

• docs/ko에 파일이 추가되면 다른 언어에도 대응 파일을 생성한다.
• docs/ko에서 파일이 삭제되면 다른 언어에서도 대응 파일을 삭제한다.
• docs/ko의 특정 파일이 수정되면 대응되는 다른 언어 파일만 다시 생성 대상으로 처리한다.
• 전체를 매번 처음부터 번역하지 않는다.
• 이미 성공한 언어/파일은 다시 번역하지 않는다.
• 실패해도 성공한 산출물까지 삭제하지 않는다.
• 실패한 대상 파일만 제거하고, 다음 실행 때 그 파일만 다시 생성한다.
• 파일 개수 비교나 단순 버전 파일로 이미 맞는 언어 폴더는 스킵한다.
• 버전 파일은 복잡한 JSON/해시보다 v1 또는 숫자처럼 단순한 형태를 사용한다.

번역 처리 기준:

• 번역은 실제 API로 테스트한다.
• mock 성공 처리는 사용하지 않는다.
• 모델의 공식 컨텍스트/출력 한계를 보고 청크 크기를 정한다.
• 입력 컨텍스트보다 실제 번역 출력이 max_tokens를 넘지 않게 자르는 것을 더 중요하게 본다.
• 청크를 번역한 직후 바로 검사한다.
• 번역 직후 검사에서 실패한 영역은 큐에 담는다.
• 큐에 담긴 실패 영역만 depth를 늘려 더 잘게 나눈 뒤 재번역/재검사한다.
• 모든 청크를 합친 뒤 마지막에 한 번만 검사하는 구조는 피한다.

검사 기준:

• 번역 결과에 한국어가 그대로 남아 있는지 확인한다.
• 공백이 사라졌는지 확인한다.
• Markdown 구조가 보존되는지 확인한다.
• 코드펜스, 링크, 이미지, 헤딩이 보존되는지 확인한다.
• 중국어처럼 길이가 줄어드는 언어는 단순 길이 비교만으로 판단하지 않는다.
• 산출물을 실제로 읽어보고 원문 대비 이상한 부분이 없는지도 확인한다.

실패 로그 기준:

• HTTP 429, 504, RemoteDisconnected, finish_reason=length, 빈 응답 같은 실패 원인을 구분한다.
• 응답 헤더, 응답 본문, 소요 시간, 모델명, 입력 크기, 토큰 사용량을 로그에 남긴다.
• 실패 하나 때문에 전체 파이프라인이 중단되거나 산출물이 사라지지 않게 한다.
• 실패가 반복되면 먼저 원인을 분석한다.

NVIDIA API 사용 기준:

• 번역 파이프라인은 NVIDIA API를 기준으로 테스트한다.
• gpt-oss-120b는 입력 컨텍스트가 최대 128k까지 가능하지만, NVIDIA API 정책상 출력은 4096 token 정도가 한도로 보인다.
• 입력을 크게 넣을 수 있어도 출력 한도 때문에 번역 결과가 잘릴 수 있으므로, 실제 청크 기준은 output 4096 token 제한을 기준으로 잡는다.
• 분당 40회 호출을 기준으로 시도하되, 에러가 발생하면 대기/재시도 정책을 둔다.

하드코딩 기준:

• docs/<lang>, 마커, 링크 정규식, 코드펜스 파싱 같은 구조 규칙은 사용한다.
• 특정 단어를 임의로 바꾸거나 제거하지 않는다.
• example.com을 임의 제거하지 않는다.
• 문서 파일을 일일이 경로로 등록하는 방식은 사용하지 않는다.
• 언어적 표현이나 특정 문장/단어를 억지로 치환하지 않는다.

운영 기준:

• GitHub Actions와 Mac self-hosted runner 둘 다 검토한다.
• Mac에서 실행할 때도 완료 후 자동 커밋/푸시되는 흐름으로 둔다.
• GitHub Actions처럼 진행 상황을 볼 수 있게 한다.
• 어떤 언어/파일/청크가 진행 중인지 로그로 확인할 수 있게 한다.
• 브랜치 이름, run URL, 실패 원인, 현재 진행률을 명확히 남긴다.

번역과 별개로, 최근에 재미있는 문서를 발견했다.

• Pollinations APIDOCS.md를 확인함

• curl로 API 키 없이 호출해도 텍스트 응답을 받을 수 있고, 이미지 생성도 가능한 구조로 보임

• API 키를 만들고 청구될 걱정 없이 가볍게 실험할 수 있지 않을까 싶음

• 일단 이걸 가지고 재밌는 것을 개발해봤고, 조금 더 사용해본 뒤 나중에 공개할 생각임

• Qwen Validation Debugger의 버전 분리 JSONL 슬롯 구조를 다시 정리함

  • docs_chunks는 코드 설명 근거이므로 Godot 3 코드와 Godot 4 코드별 설명/무관 설명 슬롯을 유지함
  • api_mapping과 label_prototypes는 Godot 3 전용, Godot 4 전용 JSONL을 따로 만들기보다 Godot 3 코드와 Godot 4 코드를 함께 넣어 3 -> 4 변환 근거 JSONL로 생성하는 방향으로 바꿈
  • 3 -> 4 변환 근거 JSONL의 검증 기대값은 Godot 3 코드 예, Godot 4 코드 아니오로 둠
  • 무관 변환 JSONL의 검증 기대값은 Godot 3 코드와 Godot 4 코드 모두 아니오로 둠

• 회고: docs/retrospectives/2026-07-10.md