이중 언어 데이터베이스 번역 CLI(선택 사항)
NotionNext의 사이트 다국어 기능은 NOTION_PAGE_ID=id1,en:id2 같은 형식으로 전체 사이트 언어를 전환합니다. 하지만 영문과 한국어처럼 서로 다른 두 Notion 데이터베이스 사이의 글 동기화는 기본적으로 수동 작업이 필요합니다. 이 저장소는 선택 사항으로 scripts/translate/ CLI(yarn translate 계열 명령)를 제공합니다. 이 도구는 두 언어 데이터베이스 사이에서 LLM을 사용해 자동 번역하고, 서로 대응되는 페이지 관계를 만들어 줍니다.
공식 문서 사이트 안내: 이 기능은 유지보수자 도구이며 바로 사용할 수 있는 기능은 아닙니다. 사용하지 않아도 블로그 빌드와 접속에는 영향을 주지 않습니다.
적용 시나리오
- 이미 두 개의 Notion 데이터베이스를 운영 중입니다. 예: 영어 데이터베이스 + 한국어 데이터베이스. 또한
NOTION_PAGE_ID다국어 설정과 대응되어 있습니다. - 반복 번역과 본문 수동 복사 작업을 줄이고 싶고, LLM 번역 품질과 API 비용을 감수할 수 있습니다.
위험과 제한 사항(사용 전 필독)
| 위험 | 설명 |
|---|---|
| 대상 페이지 본문 덮어쓰기 | 이미 연결된 페이지를 업데이트할 때 대상 페이지의 모든 하위 블록을 삭제한 뒤 다시 작성합니다. 사람이 직접 수정한 번역문은 translation_locked를 체크하세요. |
| 블록 유형 미지원 | column_list, table, synced_block 등은 대상 페이지에 쓰지 않습니다. 레이아웃이 원본 페이지와 다를 수 있습니다. |
| API 비용 | 기본값은 DeepSeek이며 Zhipu도 선택할 수 있습니다. TRANSLATOR_BUDGET_TOKENS_PER_RUN 상한을 설정하세요. |
| Schema 요구 사항 | 두 데이터베이스 모두 paired_with(Text), translation_locked(Checkbox), source_hash(Text) 속성을 추가해야 합니다. |
| 사이트 빌드와 무관 | 스크립트는 devDependency일 뿐이며 yarn build 배포에 포함되지 않습니다. 키는 .env.local에 넣고 저장소에 커밋하지 마세요. |
권장 절차
- Notion 통합에서 통합을 만들고, 두 데이터베이스 모두에 Connections를 추가합니다.
.env.local에NOTION_TOKEN,NOTION_DB_EN_ID,NOTION_DB_ZH_ID및 번역 API Key를 설정합니다. 루트 디렉터리의.env.example중notion-i18n-translator섹션을 참고하세요.yarn install을 실행해@notionhq/client등 개발 의존성을 설치합니다.yarn translate:diagnose로 통합이 두 데이터베이스에 접근할 수 있는지 확인합니다.yarn translate:all --dry-run으로 생성 또는 업데이트될 페이지를 출력만 합니다. Notion에 쓰지 않고 LLM도 호출하지 않습니다.- 먼저 단일 페이지로 시험 실행합니다.
yarn translate <page-url-or-id>로 확인한 뒤 문제가 없으면yarn translate:all을 실행합니다.
명령 빠른 참조
| 명령 | 역할 |
|---|---|
yarn translate <id|URL> | 단일 페이지 번역 |
yarn translate:all | 일괄 처리. 기본적으로 아직 연결되지 않은 Published 페이지만 처리 |
yarn translate:all --dry-run | 드라이런. 데이터베이스에 쓰지 않음 |
yarn translate:check | 원본 내용이 변경된 연결 페이지 목록 출력 |
yarn translate:backfill | 기존 번역문을 대화형으로 연결. LLM 호출 없음 |
yarn translate:diagnose | token과 데이터베이스 권한 확인 |
전체 매개변수, 블록 처리 규칙, 디렉터리 구조는 저장소의 scripts/translate/README.md를 참고하세요.
사이트 다국어 기능과의 관계
- 사이트 UI와 라우팅 다국어:
LANG, 쉼표로 구분한NOTION_PAGE_ID,REDIRECT_LANG등이 제어합니다. 사이트 기본 설정 · 다국어를 참고하세요. - 데이터베이스 간 본문 동기화: 이 CLI만 수행합니다. 스크립트를 실행해도 Next.js 온라인 코드는 수정되지 않습니다.
기여와 문제 제보
이 기능은 커뮤니티 PR로 도입되었습니다. 사용 중 문제가 있으면 GitHub Discussions에 남겨 주세요. --dry-run 출력도 함께 첨부하면 좋습니다. API Key는 절대 올리지 마세요.