다국어 메뉴·매뉴얼 운영

Guide Center은 **한국어(ko)와 영어(en)**를 기본 지원하며, 운영자는 관리자 콘솔에서 언어 코드를 추가해 이후의 메뉴 및 매뉴얼 번역을 등록할 수 있습니다. 언어별 데이터는 원본 시스템·노드·매뉴얼 식별자와 분리된 번역 테이블에 저장하므로, 추가 언어가 필요해도 코드·테이블 구조를 바꿀 필요가 없습니다.

운영 항목	저장 위치	기본 fallback
지원 언어	portal_locales	한국어, 영어
시스템명·설명	manual_system_translations	한국어 번역 → 기본 시스템 값
노드명·메뉴 경로	manual_node_translations	한국어 번역 → 기본 노드 값
매뉴얼 제목·요약·HTML	manual_page_translations	한국어 번역 → 기본 매뉴얼 값

관리자는 관리자 콘솔에서 편집 언어를 선택한 뒤 시스템 및 노드의 수정 버튼을 사용하여 해당 언어의 이름과 메뉴 경로를 등록합니다. 새 메뉴와 노드는 한국어 기본값으로 생성하며, 이후 다른 언어를 선택해 번역을 등록합니다. 매뉴얼은 웹에디터 상단의 작성 언어 선택기에서 언어를 선택하고 저장합니다. 같은 매뉴얼 페이지에 대한 번역은 독립적으로 보관됩니다.

배포 플랫폼 Shell을 사용할 수 없는 경우에도 배포가 멈추지 않도록 배포 플랫폼의 웹 서비스의 Build Command는 pnpm db:ensure-i18n을 실행합니다. 이 스크립트는 CREATE TABLE IF NOT EXISTS와 ON DUPLICATE KEY UPDATE만 사용하므로 이미 다국어 테이블과 기본 언어가 있는 DB에서도 안전하게 재실행됩니다. 기존 핵심 테이블을 변경하거나 삭제하지 않습니다.

pnpm install --frozen-lockfile && pnpm db:ensure-i18n && pnpm build

새 번역이 아직 등록되지 않은 언어를 사용자가 선택하더라도 메뉴와 매뉴얼은 한국어 번역을 우선으로, 그 다음에는 기존 기본값으로 보여 줍니다. 이 정책은 빈 화면이나 깨진 메뉴 대신 점진적인 다국어 전환을 가능하게 합니다.

외부 Aiven·R2 연결을 포함한 운영 통합 테스트는 자격 증명을 노출하지 않도록 기본 테스트에서 실행하지 않습니다. 운영 검증 환경에서만 아래와 같이 명시적으로 실행합니다.

RUN_EXTERNAL_INTEGRATION=true pnpm test