버전 업데이트에 대비한 번역 비교 도구와 유지 절차 추가

새 원문과 이전 한국어를 키별로 비교해 추가와 변경 및 삭제를 구분한다. 배포 파일 변경 비교와 기준 해시 및 후속 작업 문서를 추가했다. 자동 검사 4개와 UI 문구 1496개 비교 및 기존 배포 파일 492개 무결성 검사를 통과했다. 운영 앱과 DB는 변경하지 않았으며 기존 배포 커밋 eddda22를 보존한다. 코드와 도움말 이식 및 새 버전 실행 검증은 대상 버전 작업 때 수행한다.
2026-09-20 20:30:00 +09:00
parent eddda22eb6
commit 426a416e7b
8 changed files with 226 additions and 0 deletions
@@ -0,0 +1,80 @@
+# 버전 업데이트와 추가 번역
+
+이 저장소는 Trilium 한국어 배포판 전용이다. 게임 저장소나 게임 문서에 작업 기록을 넣지 않는다.
+
+현재 운영 기준은 Trilium 0.95.0과 한국어 배포판 2.0.0이다. 다음 버전 번역을 이어 갈 준비를 위한 도구이며 최신 Trilium 지원을 완료한 것은 아니다. 기존 배포 파일과 운영 데이터는 이 도구로 변경하지 않는다.
+
+## 이어서 작업할 자료
+
+| 대상 | 기준 자료 | 다음 버전에서 할 일 |
+|---|---|---|
+| UI 번역 | `localization/baseline.json`의 영문과 한국어 파일 | 키와 원문을 비교한 뒤 새 문구와 변경된 문구 번역 |
+| 서버 번역 | `release/app/assets/translations/ko/server.json` | 같은 버전의 공식 영문을 확보한 뒤 비교 도구에 명시적으로 전달 |
+| 직접 수정한 코드 | `release/app/main.cjs`와 `release/app/public/src` | 새 버전 원본 소스에서 해당 기능을 찾아 번역 키로 수정 |
+| 도움말 | `release/app/assets/doc_notes/en` | 원본 문서의 변경 내용과 내부 링크를 대조 |
+| 예제와 PDF | `tools/demo-source`와 `tools/build-demo-archive.py` | 새 예제 구조와 노트 연결을 확인한 뒤 새 설치 환경에서 검사 |
+| 이미지 | 도움말 이미지와 한국어 설명 | 원본 이미지를 유지하고 설명을 보완하는 기존 정책 유지 |
+| 변경 이력 | `updates/2026-09-05` | 과거 작업의 참고 자료로 보존 |
+
+`tools/build-release.mjs`는 0.95.0용 과거 작업 결과를 다시 모으는 도구다. 새 버전 이식 도구로 사용하지 않는다. 예제 생성 도구도 기존 노트 구조에 맞춰져 있으므로 새 버전에 바로 적용하지 않는다.
+
+## 1. 원본과 작업 기준 확보
+
+운영과 분리된 작업 폴더에서 대상 버전의 공식 소스와 배포 이미지를 확보한다. 버전과 커밋 및 이미지 다이제스트를 기록한다. 작업 브랜치는 `translation/대상버전` 형태로 구분한다. 기존 데이터와 비밀 파일은 저장소에 넣지 않는다.
+
+영문 파일은 반드시 대상 버전에서 가져온다. 현재 저장소에 이전 서버 영문 사전은 없으므로 한국어 파일을 영문 기준으로 간주하면 안 된다. UI 기준은 `localization/baseline.json`에 경로와 SHA-256을 고정했다.
+
+## 2. UI 문구 비교
+
+Node.js 20 이상에서 저장소 루트를 기준으로 실행한다. 출력 폴더는 아직 존재하지 않는 경로를 지정한다.
+
+```bash
+node tools/translation-upgrade.mjs 대상버전 /작업/새버전/translation.en.json /작업/번역검토
+```
+
+다른 사전이나 이후 버전의 검토 완료 자료를 기준으로 삼을 때는 이전 영문과 한국어를 함께 지정한다.
+
+```bash
+node tools/translation-upgrade.mjs 대상버전 /작업/새영문.json /작업/서버검토 /작업/이전영문.json /작업/이전한국어.json
+```
+
+`review.json`에는 키 경로와 새 원문 및 이전 원문과 한국어 후보가 함께 들어간다.
+
+| 상태 | 처리 |
+|---|---|
+| `reusable` | 원문과 자리표시자가 같아 재사용 후보로 분류됨. 화면 문맥은 확인해야 함 |
+| `added` | 새 키. 한국어를 새로 작성 |
+| `source-changed` | 원문이 바뀜. 이전 한국어를 참고해 다시 번역 |
+| `missing` | 한국어가 없거나 빈 문자열임 |
+| `placeholder-mismatch` | 변수 자리표시자가 다름. 적용 전 수정 |
+| `review-identical` | 원문과 번역이 같음. 고유 명칭인지 미번역인지 확인 |
+| `removed` | 새 사전에서 없어짐. 이전 기록에만 보존 |
+
+이 도구는 i18next 중괄호 변수와 템플릿 변수 및 일반 printf 자리표시자를 비교한다. 모든 메시지 문법이나 HTML 및 복수형 의미를 검증하지는 않는다. 새 원문과 한국어를 검토한 뒤 대상 버전의 번역 파일에 반영한다. JSON 키를 바꾸거나 원문이 바뀐 문구에 이전 한국어를 일괄 덮어쓰지 않는다.
+
+## 3. 코드와 도움말 수정 대상 비교
+
+공식 이전 이미지와 새 이미지에서 앱 파일을 각각 별도 폴더로 추출한다. 두 폴더 모두 `main.cjs`와 `assets` 등이 바로 아래에 있어야 한다.
+
+```bash
+node tools/translation-files.mjs /작업/이전원본앱 /작업/새원본앱 /작업/파일비교.json
+```
+
+현재 배포판의 수정 대상 492개 경로를 비교한다. 변경되거나 이동한 파일은 수동 검토 대상으로 삼는다. 한국어판에만 있는 파일도 별도로 표시한다. 새 버전에 추가된 다른 파일은 이 목록에 없으므로 공식 소스의 버전 간 Git diff도 함께 확인한다.
+
+빌드된 `main.cjs`를 새 버전에 덮어쓰지 않는다. 바뀐 기능을 원본 소스에서 찾아 번역 기능을 연결하고 다시 빌드한다. 공식 기여를 준비할 때도 UI 사전과 번역 기능 추가 및 도움말 변경을 나누어 검토한다.
+
+## 4. 검증과 배포
+
+1. 자연스러운 한국어와 변수 및 링크를 검사한다. 문장을 잇기 위한 쉼표를 사용하지 않는다.
+2. 대상 버전 소스의 빌드와 관련 검사를 수행한다.
+3. 별도 Docker 환경에서 신규 설치와 한국어 선택 및 기본 예제를 확인한다.
+4. 운영 데이터의 백업 사본으로 업데이트와 첨부 파일 및 검색을 확인한다.
+5. 실패 시 이전 이미지와 해당 버전 데이터 백업으로 복원할 수 있는지 검사한다.
+6. 기반 이미지와 배포 버전 및 생성 도구를 새 버전에 맞춰 수정한다. 파일 해시 검증과 실제 화면 확인을 마친 뒤 배포한다.
+
+## 5. 다음 작업을 위한 기록
+
+검토를 마친 새 영문과 한국어 사전의 경로와 해시를 새 기준으로 기록한다. 이전 기준은 Git 기록에 보존한다. `PROJECT_MEMORY.md`와 `수정기록.txt`에 버전과 변경 내용 및 검사 결과와 배포 여부를 남긴다. 번역 검토 자료는 비밀값이 없는지 확인한 뒤 해당 버전 폴더에 보관한다. 운영 노트를 기록할 때는 Trilium의 `Ubuntu 서버 운영` 아래 기존 Trilium 분류를 찾아 사용한다.
+
+이번 준비 작업은 운영 앱과 데이터베이스를 변경하지 않는다. 새 버전 자동 배포나 자동 번역을 예약하지 않는다.