docs: 한글화 운영 적용본과 도움말 100개 작업 기록 보관

2026-09-06 05:06:00 +09:00
parent 1752fed118
commit 0814e9f44c
632 changed files with 117034 additions and 0 deletions
@@ -0,0 +1,107 @@
+# 상세 변경 기록
+
+## 작업 기준
+
+사용자가 요청한 범위는 기본 예제와 도움말 및 화면에 나타나는 문구 전체의 한국어화입니다. 한국어 문장은 짧고 자연스럽게 작성하며 영어식으로 쉼표를 이어 붙이는 표현을 줄였습니다. API 이름과 변수 및 문법에 필요한 쉼표와 속성 키는 실행 호환성을 위해 유지했습니다.
+
+대상은 운영 중인 TriliumNext 0.95.0과 CKEditor 45.2.0입니다. 기존 UI 번역 위에 수정했습니다. 기존 릴리스 설명의 번역률을 이번 작업 전체의 완료율로 사용하지 않습니다.
+
+## 1. 기본 예제 148개 적용
+
+환영 문서와 글자 서식 및 표와 체크리스트를 자연스러운 한국어로 정리했습니다. 책과 업무 및 기술 자료의 제목과 본문도 번역했습니다. 오래된 사실을 담은 예제는 원문 작성 당시의 설명임을 드러내도록 조정했습니다.
+
+Mermaid 도표 13개의 사용자 표시 문구를 번역했습니다. 캔버스 글자와 마인드맵의 주제 및 메모 등 구조화된 본문도 번역했습니다. JavaScript 예제에서는 설명 주석과 화면 표시 문자열을 수정했습니다.
+
+일부 코드 노트의 제목은 모듈 식별자 생성에 사용됩니다. 따라서 `표 표시 (renderTable)`처럼 한국어 설명과 원래 식별자를 함께 유지했습니다. 연결 주소와 노트 참조 ID 및 구조화 자료의 항목 ID를 보존했습니다.
+
+### 적용 방식
+
+앱 시작 시 `korean-notes-pending.json`을 읽는 이전 훅을 추가했습니다. 모든 변경 대상의 기존 제목과 본문 SHA-256을 먼저 확인한 뒤 앱의 트랜잭션과 노트 저장 API로 변경합니다. 본문이 바뀌는 노트는 이전 내용을 수정 이력으로 보관합니다. 이미 반영된 항목은 건너뛰고 완료된 계획 파일은 이름을 바꿉니다.
+
+기록된 적용 결과는 `applied: 148`과 `unchanged: 0`입니다. 직접 SQLite 테이블에 번역문을 써 넣는 방식 대신 앱의 저장 처리를 사용했습니다.
+
+### 검증
+
+- 본문의 링크와 이미지 주소 및 노트 참조 목록 비교
+- 체크박스 태그 보존 확인
+- 코드 노트 제목에서 생성되는 영문 식별자 일치 확인
+- JavaScript 구문 검사. 예제 코드를 실제 실행하지는 않음
+- 구조화 자료의 ID 보존 확인
+- 앱의 일관성 검사 통과
+
+정적 검사만으로 Mermaid의 모든 화면이나 PDF와 이미지의 한국어화를 완료한 것은 아닙니다.
+
+## 2. 편집기와 일반 화면
+
+편집기 언어가 영어로 고정되어 있던 부분을 한국어로 바꾸고 공식 한국어 사전과 Trilium 전용 문구를 연결했습니다. 사전 항목은 719개입니다.
+
+번역 경로를 거치지 않는 메뉴도 수정했습니다.
+
+| 원래 표시 | 변경 후 |
+|---|---|
+| Text formatting | 글자 서식 |
+| Block align | 블록 정렬 |
+| Admonition | 안내 상자 |
+| Note | 참고 |
+| Tip | 도움말 |
+| Important | 중요 |
+| Caution | 주의 |
+| Warning | 경고 |
+
+일반 화면의 안내 문구 90개 항목을 조정했습니다. 속성 설명과 인쇄 용지 및 제목 템플릿 등의 설명을 한국어 어순에 맞췄습니다.
+
+운영 브라우저에서 편집 도구 모음의 글자 서식과 안내 상자 및 표 삽입 등의 한국어 표시를 확인했습니다.
+
+## 3. 캔버스와 마인드맵 및 이모지
+
+캔버스에 `ko-KR` 언어 설정을 전달했습니다. 마인드맵에는 `ko` 설정을 지정하고 항목 추가와 이동 및 삭제와 연결 메뉴를 자연스러운 표현으로 조정했습니다. 별도 메뉴 플러그인의 한국어 사전도 추가했습니다.
+
+이모지 자료는 Unicode CLDR의 한국어 이름과 검색어로 변환했습니다. 표시 선택자 차이를 정규화한 뒤 대조했으며 원본 목록에서 한국어 이름을 찾지 못한 항목은 0개였습니다. 이모지 자체와 기술용 단축 이름은 유지했습니다.
+
+이 파일들은 운영 서버에 반영했습니다. 캔버스와 마인드맵의 개별 화면 조작 검증은 남아 있습니다.
+
+## 4. 브라우저 캐시와 배포
+
+최초 적용 후 브라우저가 기존 자산을 사용하는 문제가 있어 자산 URL 접두사의 버전 표기를 바꿨습니다. Express의 같은 자산 경로 매핑을 사용하므로 물리 폴더를 새로 만들 필요는 없습니다.
+
+- 첫 수정: `assets/v0.95.0-ko-20260905`
+- 후속 편집기 배포: `assets/v0.95.0-ko-20260905-r2`
+
+추가된 바인드 마운트는 `ckeditor-ko.js`와 `ckeditor5.js` 및 `MindElixir.js`와 `emoji-ko.json`입니다. 기존 레이아웃과 번역 파일 및 서버 번들 마운트는 유지했습니다.
+
+배포 후 상태 검사에 성공했습니다. `layout_commons.js`와 `ckeditor-ko.js` 및 `ckeditor5.js`와 `MindElixir.js` 및 `emoji-ko.json`의 실제 HTTP 응답이 배포 파일과 SHA-256으로 일치하는지 확인했습니다.
+
+## 5. 기본 도움말 100개 준비
+
+전체 173개 HTML 파일 중 100개를 처리했습니다. 원래 비어 있는 파일 3개도 이 수에 포함되며 처리율은 57.8%입니다. 도움말 제목 메타데이터와 나머지 73개 본문은 작업 중입니다. 이번 도움말은 운영 서버에 아직 적용하지 않았습니다.
+
+번역 범위에는 탐색과 노트 유형 및 서식과 가져오기·내보내기 및 서버 설치와 스크립트 예제가 포함됩니다. 스크립트의 입력란 별칭과 오류 메시지도 번역했습니다. 날짜 표시 예제에는 한국어 로캘을 지정했습니다. ETAPI 예제의 실제처럼 보이는 예시 토큰은 `YOUR_ETAPI_TOKEN`으로 바꿨습니다.
+
+`build-docs.mjs`는 원본의 링크와 이미지 태그를 재사용합니다. 처리한 100개 문서 모두 링크와 이미지 경로의 목록 비교를 통과했습니다. 이미지 파일 안의 영문은 이 검사 범위에 포함되지 않습니다. 전체 도움말 폴더를 준비본으로 덮어쓰면 누락 파일이 생길 수 있으므로 일괄 마운트하지 않습니다.
+
+## 6. 백업 기록
+
+```text
+/www/dk_project/dk_app/trilium/backups/korean-20260905-071413
+/www/dk_project/dk_app/trilium/backups/before-korean-apply-20260905-102641
+/www/dk_project/dk_app/trilium/patched/main.cjs.before-cache-fix-20260905-102946
+/www/dk_project/dk_app/trilium/backups/before-korean-ui-phase2-20260905-154240
+```
+
+DB 백업은 SQLite 백업 API로 생성했습니다. 후속 UI 배포는 DB 변경 없이 파일만 수정했으므로 변경 대상 파일과 Compose 구성을 백업했습니다. 원본 백업은 서버에 보관하며 Git에는 넣지 않습니다.
+
+## 7. 남은 작업
+
+1. 도움말 73개 번역과 도움말 제목 메타데이터 번역
+2. 완성한 도움말의 의미 검토와 서버 적용 및 화면 확인
+3. 기본 예제의 속성 별칭과 할 일 상태 접두사 및 통계 화면의 표시 값 점검
+4. PDF 본문과 이미지 속 영문 범위 점검
+5. Mermaid와 캔버스 및 마인드맵의 실제 렌더링 검증
+6. 서버 메시지와 날짜 로캘 및 기타 하드코딩 문구 추가 점검
+7. 예제 복원용 원본 패키지와 향후 재설치 시 적용 범위 확인
+
+전체 완료 표시는 하지 않았습니다. 현재 운영 적용본과 준비본을 분리해 다음 작업에서 완료 여부를 과장하지 않도록 기록합니다.
+
+## 8. Gitea 등록 전 검사
+
+날짜별 작업 폴더에서 도움말 빌더와 예제 검증기를 다시 실행했습니다. 도움말 100개와 예제 변경 148개 모두 해당 정적 검사를 통과했습니다. `deployed/`의 파일 10개를 현재 운영 서버 파일과 SHA-256으로 대조해 전부 일치함을 확인했습니다. 파일 전송 과정의 변경 여부는 `node verify-snapshot.mjs`로 검사할 수 있습니다.