용어집

용어집 파일은 번역 전반에 걸쳐 일관된 용어를 보장합니다. 특정 용어를 어떻게 번역할지 또는 번역하지 않을지 정의하면, yaku가 이 규칙을 LLM 프롬프트에 주입합니다.

빠른 시작

작업 디렉토리에 .yaku-glossary.yaml 파일을 생성합니다:

ko:
  deployment: 배포          # 항상 이렇게 번역
  container: 컨테이너
  Kubernetes: ~              # 그대로 유지
  Docker: ~                  # 그대로 유지

이제 평소처럼 번역합니다. yaku가 용어집을 자동으로 로드합니다:

yaku --to ko -f docs.en.md

LLM에 다음과 같은 지시가 전달됩니다:

“다음 특정 번역을 사용하세요: deployment → 배포, container → 컨테이너”
“다음 용어는 원래 언어 그대로 유지하세요 (번역하지 마세요): Kubernetes, Docker”

파일 형식

용어집 파일은 YAML을 사용합니다. 용어는 대상 언어 코드별로 그룹화됩니다:

<대상-언어>:
  <용어>: <번역>     # 이 값으로 번역
  <용어>: ~           # 원래 언어 유지 (YAML null)

하나의 파일에 여러 언어 섹션을 포함할 수 있습니다:

ko:
  container: 컨테이너
  Kubernetes: ~

ja:
  container: コンテナ
  Kubernetes: ~

yaku는 --to 대상 언어와 일치하는 섹션만 로드합니다(대소문자 무관). 예를 들어, --to ko는 ko:, KO:, Ko:와 일치합니다. 일치하는 섹션이 없으면 yaku는 빈 용어집을 사용합니다.

번역 항목

문자열 값을 제공하여 용어를 어떻게 번역할지 정의합니다:

ko:
  software: 소프트웨어
  database: 데이터베이스
  machine learning: 머신러닝

yaku가 ko로 번역할 때, 이 용어들을 필수 번역으로 LLM 프롬프트에 주입합니다.

원문 유지 항목

~(YAML null)을 사용하여 용어를 원래 언어로 유지하도록 지시합니다:

ko:
  Kubernetes: ~
  Docker: ~
  API: ~
  GitHub: ~

브랜드명, 고유명사, 번역하면 안 되는 기술 용어에 유용합니다.

파일 탐색

--glossary <경로>를 사용하면 yaku는 해당 파일만 로드합니다. 그렇지 않으면 두 기본 위치를 모두 확인하고 병합합니다(나중 파일의 용어가 이전 것을 재정의):

~/.config/yaku/glossary.yaml — 모든 프로젝트에 공유되는 전역 용어 (먼저 로드)
.yaku-glossary.yaml (현재 작업 디렉토리) — 프로젝트별 용어 (나중에 로드, 우선)

두 파일 모두 존재하면 로드됩니다. 같은 용어가 둘 다에 있으면 프로젝트별 파일이 우선합니다.

용어집 로드를 완전히 건너뛰려면:

yaku --to ko --no-glossary -f docs.en.md

예제: 프로젝트별 + 전역 용어집

변경하지 않을 브랜드명을 위한 전역 용어집을 설정합니다:

ko:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

ja:
  GitHub: ~
  Docker: ~
  Kubernetes: ~

그런 다음 각 프로젝트에 프로젝트별 용어를 추가합니다:

ko:
  container: 컨테이너
  deployment: 배포
  service: 서비스

/path/to/my-project/에서 yaku --to ko를 실행하면 두 파일이 모두 로드됩니다. 전역 용어집은 브랜드명을 유지하고, 프로젝트 용어집은 도메인 용어를 강제합니다.

명시적 용어집 경로

yaku --to ko --glossary ~/work/shared-terms.yaml -f docs.en.md

--glossary를 사용하면 해당 파일만 로드됩니다. 기본 경로는 건너뜁니다.

작동 방식

로드 — yaku가 용어집 파일을 읽고 --to 언어 섹션을 찾습니다.
주입 — 번역 항목은 "다음 특정 번역을 사용하세요: software → 소프트웨어"가 됩니다. 원문 유지 항목은 "다음 용어는 원래 언어 그대로 유지하세요: Kubernetes, Docker"가 됩니다.
번역 — LLM이 텍스트와 함께 용어집 지시를 봅니다.
검증 — 번역 후 yaku는 안전 검사(EnforceKeepOriginal)를 실행하여 ~로 표시된 용어가 출력에 여전히 존재하는지 확인합니다. 이는 안전망이며, 주요 강제는 프롬프트를 통해 이루어집니다.

프롬프트 주입 방식이므로 용어집은 모든 백엔드(Gemini, OpenAI, Anthropic, hosted)와 모든 포맷(텍스트, Markdown, JSON, YAML)에서 작동합니다.

전체 예제: 요리 블로그 번역

ko:
  # 요리 이름은 원래 언어로 유지
  ratatouille: ~
  croissant: ~
  miso: ~
  dashi: ~

  # 요리 용어 통일
  sauté: 소테
  julienne: 줄리엔 커팅
  mise en place: 미장플라스

ja:
  ratatouille: ~
  croissant: ~
  sauté: ソテー
  julienne: 千切り

yaku --to ko -f recipe.en.md -o recipe.ko.md

용어집을 사용하면 좋은 경우

오픈 소스 프로젝트 — 번역 전반에 걸쳐 브랜드명과 기술 용어를 일관되게 유지합니다.
문서 사이트 — 표준 용어를 강제합니다(예: “container”는 항상 “컨테이너”로).
규제 산업 — 법률 또는 의학 용어의 번역을 고정합니다.
다수 번역자 워크플로 — 모든 사람이 같은 어휘를 사용하도록 보장합니다.

팁

작게 시작하세요. 불일치를 발견할 때만 용어를 추가하세요. 10~20개 용어면 대부분의 프로젝트를 커버합니다.
브랜드명에는 ~를 사용하세요. “GitHub”, “Kubernetes”, “Docker” 같은 용어는 거의 항상 그대로 유지해야 합니다.
보편적인 용어에는 전역 용어집을 사용하세요. 브랜드명과 일반 기술 용어를 ~/.config/yaku/glossary.yaml에 넣어 모든 곳에 적용하세요.
프로젝트별 용어집은 작업 디렉토리에 배치하세요. yaku는 명령을 실행하는 디렉토리에서 .yaku-glossary.yaml을 찾습니다.
--context와 함께 사용하세요. 용어집은 특정 용어를 처리하고, --context는 전체적인 어조와 도메인을 설정합니다.