왜 yaku인가?

yaku는 터미널에서 텍스트, 파일, 구조화된 문서를 번역하는 CLI 도구입니다. 설치 후 yaku --to ko "Hello"를 실행하면 번역이 완료됩니다. API 키, 계정, 설정이 필요 없습니다.

내부적으로 yaku는 실제 파일을 처리하도록 설계되어 있습니다. Markdown을 서식 깨트림 없이 번역하고, JSON과 YAML의 값만 번역하면서 키는 그대로 유지하며, 용어집 파일로 용어 일관성을 강제할 수 있습니다. stdin, 파일 또는 인수로 입력을 받아 stdout으로 출력하므로 스크립트와 파이프라인에 자연스럽게 통합됩니다.

이 페이지는 yaku가 필요에 맞는 도구인지 판단하는 데 도움을 줍니다.

yaku가 하는 것

언어 간 텍스트 번역 — LLM 백엔드가 지원하는 모든 언어 쌍.
글 다듬기 — 외국어로 작성한 텍스트의 문법과 유창성을 번역 없이 개선합니다.
구조 보존 — Markdown, JSON, YAML의 서식을 깨트리지 않고 번역합니다. 키, 코드 블록, URL, 프론트 매터는 그대로 유지됩니다.
용어 관리 — 용어집 파일로 특정 용어의 번역을 고정하거나 번역하지 않도록 설정합니다.
파이프라인에 통합 — 기본적으로 stdin/stdout을 사용하며, curl, gh, git, jq 등 모든 CLI 도구와 조합할 수 있습니다.

yaku가 하지 않는 것

yaku의 범위는 언어 장벽을 넘는 것을 돕는 것입니다. 이 범위 밖의 기능은 의도적으로 제외됩니다:

범위 외	대신 사용할 도구
코드 생성 또는 설명	범용 AI CLI (`llm`, `aichat`, `sgpt`)
텍스트 요약	범용 AI CLI
질의응답 또는 채팅	ChatGPT, Claude 또는 범용 AI CLI
포맷 변환 (예: Markdown → HTML)	`pandoc`
번역 컨텍스트 없는 맞춤법 검사	`aspell`, `languagetool`
GUI 기반 번역	Google 번역, DeepL

간단한 기준: 언어 장벽을 넘는 작업이 아니라면, yaku는 적절한 도구가 아닙니다.

yaku와 다른 도구 비교

vs. Google 번역 / DeepL / ChatGPT

이들은 브라우저 기반 도구입니다. 터미널을 떠나 텍스트를 복사하고, 붙여넣고, 결과를 받아 다시 붙여넣습니다. yaku는 이 컨텍스트 전환을 없앱니다:

# 브라우저에 복사-붙여넣기 대신:
echo "Hello, how are you?" | yaku --to ko
cat error.log | yaku --to ko --context "nginx 오류 로그"
yaku --to ko -f README.en.md -o README.md

yaku는 또한 파일 구조(JSON 키, Markdown 서식)를 보존하고 용어집 기반 용어 관리를 지원합니다. 브라우저 도구에는 없는 기능입니다.

vs. 범용 AI CLI (`llm`, `sgpt`, `aichat`)

이 도구들은 LLM에 임의의 프롬프트를 보냅니다. 번역에 사용할 수는 있지만, 매번 프롬프트를 직접 작성해야 합니다:

# 범용 AI CLI를 사용하는 경우:
echo "Hello" | llm "이것을 한국어로 번역해 줘"

# yaku를 사용하는 경우:
echo "Hello" | yaku --to ko

차이점:

	yaku	범용 AI CLI
프롬프트 엔지니어링	번역 품질에 최적화된 내장 프롬프트	직접 프롬프트 작성
포맷 보존	Markdown, JSON, YAML 자동 처리	수동 (LLM이 지시를 따르기를 바람)
용어집 지원	내장 (`.yaku-glossary.yaml`)	없음
출력 정리	정제됨 — “번역 결과입니다:” 같은 불필요한 서문 없음	원시 LLM 출력
범위	번역과 다듬기만	프롬프트로 가능한 모든 것

모든 AI 작업을 위한 만능 도구가 필요하면 llm이나 aichat을 사용하세요. 일관된 용어로 신뢰할 수 있는 구조화된 번역이 필요하면 yaku를 사용하세요.

vs. Translate Shell (`trans`)

Translate Shell은 LLM이 아닌 전통적인 번역 엔진(Google, Bing)을 사용합니다. 빠르고 무료이지만:

포맷 인식 없음 — JSON/YAML 키를 보존하며 번역 불가
용어집 또는 용어 관리 없음
기본 엔진의 한계로 번역 품질이 제한적 (종종 직역, 부자연스러움)
다듬기 모드 없음

Translate Shell은 빠른 조회에 적합합니다. yaku는 개발 출력물, 구조화된 파일, 품질이 중요한 번역에 더 적합합니다.

yaku를 사용하면 좋은 경우

개발 출력물(문서, i18n 파일, README, 오류 메시지)을 정기적으로 번역하는 경우.
프로젝트 전체에서 일관된 용어가 필요한 경우 (용어집).
구조화된 파일(Markdown, JSON, YAML)을 다루며 구조를 보존해야 하는 경우.
외국어로 작성한 텍스트를 다듬고 싶은 경우.
스크립트나 CI/CD 파이프라인에 번역을 포함시키고 싶은 경우.

yaku를 사용하지 않는 것이 좋은 경우

범용 AI 어시스턴트가 필요한 경우 — yaku는 번역과 다듬기만 합니다. 코드 생성, 요약, Q&A에는 llm, aichat, sgpt를 사용하세요.
실시간 대화형 상호작용이 필요한 경우 — yaku는 상태 비저장(입력 하나, 출력 하나)입니다. 주고받는 대화에는 ChatGPT나 Claude를 사용하세요.
설정 없이 완전한 오프라인 번역이 필요한 경우 — yaku는 인터넷 접속(호스팅 백엔드) 또는 로컬에서 실행 중인 LLM(예: Ollama)이 필요합니다. 모델을 내장하지 않습니다.
GUI 기반 번역이 필요한 경우 — yaku는 터미널 전용입니다. 브라우저 기반 워크플로에는 Google 번역이나 DeepL을 사용하세요.