문서 번역

이 프로젝트는 AWS Bedrock의 Haiku 3.5 모델을 사용하여 영어 문서를 여러 언어로 자동 번역합니다. 번역 시스템은 효율적이고 정확하며 사용하기 쉽도록 설계되었습니다.

지원 언어

현재 다음 언어가 지원됩니다:

일본어 (jp)
프랑스어 (fr)
스페인어 (es)
독일어 (de)
중국어 (zh)
한국어 (ko)

작동 방식

번역 시스템은 다음 방식으로 작동합니다:

h2 헤더별로 문서 분할 - 더 효율적인 처리와 번역 모델을 위한 향상된 컨텍스트 제공
마크다운 형식 보존 - 모든 마크다운 구문, 코드 블록, HTML 태그가 번역 중에 유지됨
프론트매터 특수 처리 - YAML 프론트매터 구조를 유지하면서 번역
증분 번역 - 기본적으로 변경된 파일만 번역하여 시간과 리소스 절약

로컬에서 번역 실행

문서를 로컬에서 번역하려면 scripts/translate.ts 스크립트를 사용하세요:

# 변경된 파일만 일본어로 번역 (기본값)
./scripts/translate.ts

# 모든 파일 번역
./scripts/translate.ts --all

# 특정 언어로 번역
./scripts/translate.ts --languages jp,fr,es

# 실제 번역 없이 예상 결과 확인
./scripts/translate.ts --dry-run

# 상세 출력 모드
./scripts/translate.ts --verbose

GitHub 워크플로

GitHub 워크플로는 풀 리퀘스트에서 영어 문서 파일이 변경될 때 자동으로 문서를 번역합니다. 이 워크플로는:

영어 문서 파일 변경 사항 감지
AWS Bedrock을 사용하여 변경된 파일 번역
번역본을 소스 브랜치에 커밋
PR에 번역 상태 업데이트

수동 워크플로 트리거

GitHub Actions 탭에서 수동으로 번역 워크플로를 시작할 수 있습니다. 이 기능은 다음에 유용합니다:

모든 문서 전체 번역 실행
특정 언어로 번역
번역 스크립트 변경 후 번역 업데이트

AWS 설정

번역 시스템은 AWS Bedrock의 Haiku 3.5 모델을 사용합니다. 이 기능을 사용하려면 다음이 필요합니다:

AWS 자격 증명 - 로컬 개발 시 AWS CLI 또는 환경 변수를 사용하여 설정
IAM 역할 - GitHub Actions용 OIDC 인증과 AWS Bedrock 권한이 구성된 IAM 역할

필요한 권한

IAM 역할 또는 사용자에게 다음 권한이 필요합니다:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/anthropic.claude-3-haiku-20240307-v1:0"
      ]
    }
  ]
}

번역 품질

번역 품질은 일반적으로 높지만 다음 사항에 유의하세요:

기술 용어 - 영어 기술 용어가 보존되도록 설정됨
코드 블록 - 원본 형식 유지를 위해 번역되지 않음
컨텍스트 인식 - 문서 컨텍스트를 이해하는 번역 모델이 기술 문서 번역에 도움

번역 사용자 정의

scripts/translate.ts 파일을 수정하여 번역 프로세스를 사용자 정의할 수 있습니다. 가능한 사용자 정의 옵션:

추가 언어 지원
번역 모델 변경
번역에 사용되는 프롬프트 조정
문서 분할 및 처리 방식 수정

문제 해결

번역 과정에서 문제가 발생하면 다음을 확인하세요:

AWS 자격 증명 - AWS 자격 증명이 올바르게 설정되었는지 확인
AWS 리전 - AWS Bedrock이 사용 가능한 리전 사용 확인
상세 출력 모드 실행 - --verbose 플래그 사용하여 상세 로그 확인
속도 제한 확인 - 대규모 번역 작업 시 AWS Bedrock의 속도 제한 영향 확인