다국어 자동화: 나의 AI-Powered Markdown Translator

프로젝트 보기 → GitHub

저는 여러분께 제 프로젝트 AI-Powered Markdown Translator를 소개하게 되어 기쁩니다. 이 오픈소스 Python 스크립트는 제 블로그의 Markdown 파일과 GitHub 저장소의 일부 README/문서를 자동으로 번역합니다. OpenAI, Mistral AI, Anthropic (Claude), Google Gemini와 같은 최첨단 AI 모델을 통합해, 이 도구는 글, README, 기술 문서를 구조와 서식을 유지한 채 14개 언어로 번역합니다. 이 프로젝트는 자동화, AI 통합, 신뢰성 엔지니어링에 대한 제 역량과, 기술 콘텐츠를 모두가 접근할 수 있게 만들고자 하는 제 열정을 잘 보여줍니다.

이건 단순한 스크립트가 아닙니다. 제 전문성과 더 포용적인 디지털 세상을 향한 비전을 증명하는 결과물입니다.

이 프로젝트를 만든 이유

Markdown 파일은 제 디지털 생태계에서 핵심적인 요소입니다. 제 블로그 글, 튜토리얼, 오픈소스 문서가 모두 여기에 담겨 있기 때문입니다. 이를 자동으로 번역함으로써, 저는 제 콘텐츠를 전 세계 독자에게 열어줍니다. 이제 제 블로그는 이 스크립트 덕분에 14개 언어로 제공되며, 약 1,800개의 번역 버전(대략적인 규모, FR 원본 제외)이 현재 jls42.org에 공개되어 있고, 발행할 때마다 숫자는 계속 늘어나고 있습니다.

v1.9(2026년 5월)은 하나의 전환점입니다. 감으로 하는 개발(vibe coding)을 AI 페어 작업(Claude Code + Codex)으로 진행하고, 산업 수준의 품질 스택(14개 훅, 229개 테스트, SonarCloud, AI 보조 PR 리뷰)으로 보호해, 한 줄 한 줄을 사람이 직접 다시 읽지 않더라도 깔끔한 코드를 목표로 삼았습니다.

스크립트가 실제로 작동하는 예시는 다음과 같습니다.

이 블로그 jls42.org의 14개 언어 버전 — 다국어 편집 경험 전체(글, 프로젝트, AI 뉴스)는 이 스크립트로 만들어집니다. 예를 들어 사이트의 독일어, 일본어, 중국어, 스페인어, 아랍어 버전을 둘러볼 수 있습니다. 번역된 편집 콘텐츠는 모두 이 스크립트를 거쳤고, 인터페이스 요소는 Astro의 기본 i18n 시스템에서 제공합니다.
프로젝트의 README 자체도 GitHub에서 14개 언어로 번역됩니다. 예: 영어, 스페인어, 중국어.

이 프로젝트는 AI가 접근성을 높이면서도 실제 문제를 해결할 수 있음을 보여줍니다.

제가 가진 역량을 보여주는 부분

이 프로젝트는 제 기술 역량을 보여주는 쇼케이스입니다. 다음과 같은 점을 강조합니다.

멀티 모델 오케스트레이션: 개발은 Claude Code의 Opus로 진행하고, 대체(fallback)는 Codex가 맡으며, 계획 검증은 GPT-5.5 reasoning extra-high가 담당하고, 병합 전 검토는 /pr-review-toolkit가 수행합니다
여러 AI API 통합: 4개 제공자(OpenAI, Mistral AI, Claude, Gemini)를 연결하고, 각 API의 특성에 맞게 적응합니다(finish_reason / stop_reason 처리, 응답 형식, 토큰 한도)
신뢰성 엔지니어링: 이중 계층의 번역 후 검증(결정론적 verbatim 누수 방지 + 확률적 langdetect), 조용한 실패(silent failures) 탐지, 명시적 상태 반환
산업 수준의 품질 스택: 14개의 자동화 훅(ruff, mypy, shellcheck, Opengrep SAST, pip-audit, Lizard…), 229개의 unittest 테스트, 11개의 SonarCloud 배지, 그리고 Codacy와 CodeFactor
오픈소스 정신: GitHub에서 제공되며, GPLv3 라이선스를 따르고, README는 14개 언어로 번역됨

이러한 요소들은 제가 장기적으로 강력하고 신뢰할 수 있으며 유지보수 가능한 도구를 만들 수 있음을 보여줍니다.

주요 기능

이 스크립트가 제공하는 기능은 다음과 같습니다.

Multi-Provider: 4개 API 지원(OpenAI, Mistral AI, Claude, Gemini)
2026 모델: 기본값으로 GPT-5.5, Claude Sonnet 4.6, Gemini 3.1 Pro
경제 모드 (--eco): 더 빠르고 비용이 적게 드는 모델 사용
단일 파일 (--file): 전체 디렉터리 대신 단일 파일 번역
이름 보존 (--keep_filename): 원래 이름과 확장자를 유지(Astro, Hugo 등에 이상적)
.env 지원: .env 파일에서 API 키를 자동으로 로드
.mdx 파일 지원: 일반적인 .md 파일 외에도 지원
서식 보존: 코드 블록, 인라인 코드, 링크, 메타데이터가 그대로 유지됨

v1.9의 새 기능(2026년 5월):

번역 후 검증: 조용한 실패(silent failures)를 자동으로 탐지합니다. 대상 언어를 확인하고, 모든 제공자에서 잘림(truncation)을 차단합니다.
다중 위치 노트 (--note_position, --note_format): 상단, 하단 또는 둘 다; GitHub의 임베드 카드(embed card)와 호환되는 레거시(legacy) 형식 또는 마커 형식(marker format)
강화된 --news 모드: v1.8에서 이미 소스 EN 인용을 placeholder로 보호하기 위해 도입되었고, v1.9에서는 복원 후 검증이 한층 강화되었습니다(잔여 placeholder = 오류, 원본 인용과 출처 URL 검증, 대상/원본 플래그 확인) — 블로그의 모든 ia-actualites 기사에 사용됩니다.

제공자	품질(기본값)	경제형 (`--eco`)
OpenAI	`gpt-5.5`	`gpt-5.4-mini`
Claude	`claude-sonnet-4-6`	`claude-haiku-4-5-20251001`
Mistral	`mistral-large-latest`	`mistral-small-latest`
Gemini	`gemini-3.1-pro-preview`	`gemini-3.1-flash-lite-preview`

v1.0 → v1.9의 진화

버전	날짜	주요 기여
1.0–1.4	2024	OpenAI, 그다음 Mistral, 그다음 Claude
1.5	2024년 9월	클라이언트 리팩터링, 2024 모델(gpt-4o, claude-3.5-sonnet)
1.6	2026년 1월	2026 모델(gpt-5, claude-sonnet-4-5, gemini-3-pro), Gemini, `--eco` 모드, 단일 파일(`--file`)
1.7	2026년 1월	`--keep_filename`, `.env`, 인라인 코드 보존
1.8	2026년 3월	기본 GPT-5.4 모델, 인용 placeholder를 사용하는 `--news` 모드
1.9	2026년 5월	번역 후 검증, 다중 위치 노트, 14개 훅 + 229개 테스트 + AI 리뷰 품질 스택

감으로 하는 개발 + 안전장치

v1.9 전체는 AI 페어 작업으로 작성되었습니다. 제 작업 흐름은 다음과 같습니다. Claude Code(오직 Opus)가 코드를 작성하고, Opus가 막히거나 사용량 한도가 찼을 때 Codex가 이어받습니다. GPT-5.5(reasoning extra-high)는 실행 전에 계획을 검증하고, /pr-review-toolkit:review-pr 스킬은 각 병합 전에 PR을 다시 읽습니다. 저는 코드를 직접 재검토하지 않습니다. 이런 개발 방식을 실제 운영 환경에서 가능하게 하려면, 그에 상응하는 안전장치 스택에 투자해야 했습니다.

14개 훅 자동화(pre-commit + pre-push): shellcheck, ruff, prettier, detect-secrets, Lizard CCN, mypy, Opengrep SAST, pip-audit, unittest
229개 테스트 unittest(새로운 v1.9 코드 기준 약 98% 커버리지)
실전 테스트: 다양한 README를 대상으로 한 멀티 저장소 테스트, 블로그에서의 제품 내부 사용(dogfooding)(운영 = 실시간 테스트), 시각적 렌더링 검증(브라우저 또는 Markdown 미리보기)
3개 외부 플랫폼: SonarCloud(11개 배지), Codacy, CodeFactor
/pr-review-toolkit:review-pr 스킬: 병합 전 다중 에이전트 AI 보조 리뷰
이중 계층 번역 후 검증: 결정론적(verbatim 누수 방지) + 확률적(langdetect)

핵심은 우리가 전통적인 엔지니어링을 잘한다는 것을 증명하려는 것이 아닙니다. 핵심은 선택의 여지가 없기 때문입니다. 사람이 다시 읽지 않은 AI 코드는 더 적은 것이 아니라 더 많은 안전장치를 필요로 합니다. 이 규율은 기술 심층 분석에 자세히 설명되어 있습니다.

이 블로그의 운영 환경에서

이 프로젝트는 스스로를 번역합니다. README는 14개 언어로 제공되며, 이 블로그의 모든 다국어 버전을 생성합니다.

블로그 글, 4개 프로젝트, 98개의 ia-actualites 글은 FR 원본을 제외하고 약 1,800개의 번역 버전을 구성합니다(콘텐츠에 따라 언어별 커버리지는 다름)
--news 모드는 소스 EN 인용을 보존하기 위해 ia-actualites 기사에 일관되게 사용됨
v1.9 안전장치는 2026년 5월부터 활성화됨: 이중 번역 후 검증을 도입한 이후, 대상 언어의 silent-failure는 더 이상 발견되지 않았습니다
메타 일관성: 여러분이 영어, 독일어, 일본어로 읽는 페이지도 이 스크립트가 번역합니다

더 자세히 알아보려면

이 v1.9가 어떻게 만들어졌는지(새 기능의 세부 내용, 멀티 모델 작업 흐름, 코드 리뷰 없이도 깔끔한 코드를 목표로 하기 위해 마련한 안전장치)를 이해하려면, 기술 심층 분석 전체본을 참고하세요.

그리고 이전 릴리스와 톤을 비교하고 싶다면, v1.5에 대한 2024년 글이 더 전통적인 release notes 형식을 따릅니다.

직접 사용해 보세요

프로젝트를 GitHub에서 확인하고, 여러분의 Markdown 파일로 테스트한 뒤, 피드백을 공유해 주세요. 여러분의 아이디어가 이 도구를 더 완성도 높게 만드는 데 도움이 됩니다!

문의 : contact@jls42.org