문서 번역과 다국어 검토 전체 가이드

이 장에서 만드는 것

한국어 Markdown 문서를 영어 번역본으로 연결하고, 반복 용어를 용어집으로 관리하며, 번역 상태를 검토한다. Free에서는 현재 문서 한 개의 초안을 만들고, Pro에서는 Binder의 변경 문서·사람이 수정한 구간·게시 준비 상태를 함께 관리한다.

번역은 원문을 대체하는 저장 명령이 아니다. Glif는 원문, 번역본, 실행에 사용한 runtime과 검토 상태를 분리해 번역본도 다시 사용할 수 있는 문서 자산으로 남긴다.

이 장의 로컬 캡처는 실제 Glif release candidate에서 Free 현재 문서 흐름을 실행한 결과다. Pro 프로젝트 작업은 live entitlement와 operation capability가 필요하고, 실제 모델 번역은 설치된 signed runtime 또는 사용자가 연결한 외부 제공자가 필요하다. 권한이나 runtime이 없는 화면을 번역 실행 성공의 증거로 사용하지 않는다.

준비물

• 번역할 Markdown 문서가 있는 Binder
• source locale과 다른 target locale
• 로컬 번역을 쓴다면 Glif가 제공하는 관리형 번역 패키지를 설치할 공간
• 외부 제공자를 쓴다면 본인이 관리하는 HTTPS endpoint, model과 API key
• Pro 프로젝트 흐름을 실습한다면 live Pro entitlement

번역 실습 Binder 내려받기

실습 Binder에는 한국어 원문 3개, 영어 번역본 2개와 용어집 예제가 있다. runtime package, API key, 계정 entitlement와 실제 실행 state는 포함하지 않는다.

번역을 구성하는 네 축

대상 언어는 Glif 인터페이스 언어 또는 사이트 기본 언어와 같은 설정이 아니다. 번역 버튼이 대상으로 삼는 locale pair이며, 선택한 runtime이 그 source-target 조합을 실제로 지원할 때만 실행할 수 있다.

Free와 Pro 경계

Free를 여러 번 실행할 수 있다는 것은 Binder 전체 atomic batch, 프로젝트 용어집 mutation 또는 게시 준비 권한을 뜻하지 않는다. Pro도 offline cache나 화면의 plan 문자열만으로 열리지 않으며 실행 시 live entitlement와 Binder 범위 capability를 다시 확인한다.

1. 번역할 문서 열기

1. 실습 Binder를 연다.
2. 01_product-story.md를 연다.
3. 에디터 헤더에서 번역 흐름 열기를 선택한다.
4. 번역 패널이 현재 문서와 source locale을 올바르게 인식했는지 확인한다.

번역 패널은 상단 launcher에서도 열 수 있다. 다만 현재 문서 초안을 만들려면 먼저 Markdown 문서를 열어야 한다. 빈 패널에서 Binder 일괄 번역으로 자동 확장하지 않는다.

2. 대상 언어 선택

패널의 사용 흐름 안내에서 다음 세 값을 먼저 읽는다.

원문 한국어 / 현재 보기 한국어 / 대상 영어

1. 대상 언어에서 영어를 선택한다.
2. source와 target이 같은지 확인한다.
3. 현재 runtime이 해당 locale pair를 지원하는지 확인한다.
4. Pro라면 대상 언어가 프로젝트 언어에 포함됐는지 확인한다.

source와 target이 같으면 실행이 차단된다. 목록에 보이는 언어라도 선택한 provider가 지원하지 않거나 capability를 확인할 수 없으면 지원하지 않는 번역 언어 조합 또는 준비 필요 상태가 표시된다.

현재 기본 UI에 노출되는 target은 한국어, 영어, 일본어, 중국어, 스페인어, 프랑스어와 독일어다. 이 목록은 모든 locale의 모델 품질 검증 완료를 뜻하지 않는다. 지역 변형과 RTL locale은 별도의 공개·품질 gate를 통과하기 전에는 기본 목록에 추가하지 않는다.

3. 관리형 로컬 번역 준비

기본 경로는 사용자가 별도 local endpoint를 설치·관리하는 방식이 아니라 Glif 관리형 로컬 번역 패키지다.

1. 대상 언어와 작업 범위를 먼저 선택한다.
2. 로컬 runtime이 없으면 로컬 번역 준비를 선택한다.
3. 다운로드 크기, 설치 후 최대 크기, peak disk 사용량과 package license를 확인한다.
4. 로컬 처리와 취소 정책을 읽고 동의한다.
5. 설치·검증·시작이 끝난 뒤 상태가 사용 가능인지 확인한다.

설치됨은 파일이 존재한다는 뜻이고 사용 가능은 현재 profile identity, runtime artifact, model artifact와 prompt 구성이 검증되어 실행할 수 있다는 뜻이다. 같은 model family가 보인다는 이유로 다른 model 또는 mutable tag를 준비 완료로 간주하지 않는다.

개발 빌드나 배포 구성이 없는 빌드에서는 관리형 패키지를 준비할 수 없다는 안전한 설명이 나타날 수 있다. 이 상태에서 임의 endpoint를 로컬 기본 경로처럼 우회 연결하지 않는다.

설치 취소와 복구

• 다운로드·설치 단계에서 취소를 요청하면 현재 단계의 취소 가능 여부를 확인한다.
• 설치 완료 직전처럼 atomic commit이 시작된 단계에서는 취소가 거절될 수 있다.
• 손상 상태에서 이전 로컬 번역 복원이 보이는 경우에만 저장된 last-known-good package를 복원한다.
• 복원은 문서, 번역본과 용어집을 수정하지 않으며 network에서 새 package를 받지 않는다.

4. 외부 제공자 연결

외부 제공자는 고급 설정에서 명시적으로 연결한다.

1. 고급 설정을 연다.
2. 추가 번역 서비스 연결에서 HTTPS 서비스 주소를 입력한다.
3. provider가 요구하는 model 또는 서비스 옵션을 입력한다.
4. API key를 입력한다.
5. 연결 테스트를 실행한다.
6. 성공한 구성을 저장하고 번역 방식에서 해당 경로를 선택한다.

원격 endpoint에는 HTTPS가 필요하다. HTTP는 loopback 주소에서만 허용한다. API key는 Markdown, Binder 설정, screenshot, log 또는 evidence JSON에 넣지 않는다. 저장된 key가 있더라도 패널은 원문을 자동 전송하지 않는다.

외부 경로로 실행하기 전에는 다음을 다시 확인한다.

• 선택한 provider
• target locale
• Free 현재 문서 또는 Pro 프로젝트 범위
• 외부 전송 동의 checkbox

대상 언어, 문서, provider 또는 작업 범위가 바뀌거나 실행이 끝나면 동의가 초기화된다. 추가 번역 서비스는 다른 실행 경로이며 더 높은 품질을 보장하는 이름이 아니다.

5. 용어집 위치와 버전 확인

Binder 용어집은 다음 경로에 저장된다.

.glif/translation/glossary.yaml

패널은 현재 Binder의 용어집 위치와 content 기반 버전을 표시한다. 용어집을 바꾸면 다음 실행에서 새 version과 관련 chunk의 glossary context를 다시 비교한다.

용어집은 번역 품질 보증서가 아니다. 제품명, 고유명사와 반복 표현을 사용자가 통제하는 준비 surface다.

6. 현재 문서에서 용어 후보 찾기

1. 현재 문서 용어를 연다.
2. 반복 또는 강조된 후보와 출처 문서를 확인한다.
3. 적용할 번역을 직접 입력하거나 원래 표기 유지를 선택한다.
4. 한 번에 저장할 항목을 확인한다.
5. 저장을 선택한다.

Free에서는 현재 문서에서 실제로 찾은 후보만 저장할 수 있고 한 번에 최대 5개다. 기존 승인 항목을 덮거나 alias와 stable ID를 바꿀 수 없다. Pro에서는 승인, 임시, 사용 중단 상태를 관리할 수 있지만 같은 term-target locale에 서로 다른 승인 번역이 있으면 프로젝트 실행을 차단한다.

7. Free 현재 문서 초안 만들기

1. 현재 문서가 맞는지 확인한다.
2. target locale과 번역 경로를 확인한다.
3. 외부 제공자라면 전송 범위에 동의한다.
4. 현재 문서 번역 초안 만들기를 선택한다.
5. 진행 중인 문서, 구간 수와 번역 경로를 확인한다.
6. 완료 카드에서 현재 문서 번역 초안 열기를 선택한다.

영어 target이라면 name.md 옆에 name.en.md가 만들어진다. 원문 파일은 덮어쓰지 않는다. 실행 출력이 Markdown 구조 검증을 통과하지 못하면 기존 정상 번역본을 교체하지 않고 검토 필요 상태로 남긴다.

8. Pro Binder 변경분 번역

Pro 프로젝트 흐름은 다음 순서다.

1. target을 프로젝트 언어로 설정한다.
2. 승인 용어집 충돌을 해소한다.
3. 현재 locale의 누락·변경·검토 필요 상태를 확인한다.
4. 변경분 번역을 실행한다.
5. 번역, 재사용, 수동 수정 보호와 건너뜀 수를 확인한다.
6. locale별 게시 준비 상태를 검토한다.

기본 실행은 모든 파일을 다시 번역하지 않는다. source hash, prompt version, glossary version, chunk identity와 human-edited state를 비교해 재사용할 구간과 다시 실행할 구간을 정한다.

강제 전체 재번역

강제 전체 재번역은 고급 작업이다. 켜면 chunk 재사용과 수동 수정 보호를 건너뛸 수 있으므로, 사람이 수정한 파일 목록과 차이를 먼저 확인하고 명시적으로 덮어쓰기를 승인해야 한다.

9. 진행, 취소와 실패

진행 카드에는 현재 파일, 전체·처리 파일 수, 구간 진행과 실행 경로가 표시된다.

• 취소가 승인되면 run은 terminal cancelled로 바뀌고 이후 결과를 쓰지 않는다.
• 결과 commit이 이미 시작됐거나 run이 terminal이면 취소 요청은 거절될 수 있다.
• 일부 파일 실패는 성공으로 숨기지 않고 완료 카드와 상태에 남는다.
• retry 가능한 실패는 실패한 문서 또는 구간만 다시 실행한다.
• 내부 경로, credential과 provider stack은 기본 오류 문구에 노출하지 않는다.

앱이 쓰기 도중 중단되면 recovery journal은 이전 또는 새 artifact 중 하나로 수렴시킨다. 재시작 사이에 사용자가 직접 고친 번역본을 오래된 journal로 덮지 않는다.

10. 번역 상태와 파일 목록 검사

번역 상태에서 현재 문서를 먼저 확인한 뒤 프로젝트 전체로 넓힌다.

파일이 많으면 처음에는 우선순위가 높은 10개만 보인다. 전체 파일 보기로 모두 펼치고, 검사를 눌러 특정 source 문서의 chunk 상태를 고정한다. 다른 locale의 요약은 현재 target 작업보다 아래에서 비교한다.

11. 사람이 수정한 번역본 검토

사람이 name.en.md를 직접 고치면 Glif는 마지막 자동 생성본과 현재 번역본을 비교한다.

1. 수동 수정 N개 검토 또는 파일의 검토를 선택한다.
2. 원문, 마지막 자동 번역본과 현재 번역본의 차이를 확인한다.
3. source와 target의 chunk 구조가 유지되는지 확인한다.
4. 현재 번역을 보존할지, 새 기준으로 승인할지, 다시 번역할지 결정한다.

기준 기록이 없는 수동 번역본이나 chunk 구조가 달라진 번역본은 자동 승인할 수 없다. 이 상태를 억지로 baseline으로 만들지 말고 원문·번역 구조를 먼저 맞춘다.

12. 현재 번역본을 새 기준으로 승인

검토 dialog에서 현재 번역본을 기준으로 승인하면 현재 target을 다음 증분 실행의 baseline으로 사용한다.

승인은 “번역 품질이 완벽하다”는 선언이 아니다. 현재 source 구조와 target 내용을 사용자가 검토했고, 이후 바뀌지 않은 구간을 재사용해도 된다는 명시적 결정이다.

파일 전체가 아니라 특정 human-edited chunk만 승인할 수도 있다. 다른 수동 수정 chunk의 보호 상태는 유지된다.

13. 필요한 구간만 다시 번역

현재 문서의 chunk 목록에서 다시 실행할 heading을 찾는다.

1. 상태와 마지막 번역 시각을 확인한다.
2. 섹션 재번역을 선택한다.
3. 외부 provider라면 현재 범위의 전송 동의를 다시 확인한다.
4. 완료 후 해당 chunk 상태와 파일 전체 human-edited 상태를 확인한다.

inventory의 high-quality retranslation path는 UI에서 번역 품질 보장으로 표현하지 않는다. 더 신중한 repair/pass를 지원하는 runtime capability가 있을 때만 별도 경로를 열며, 단순히 외부 provider를 고른 것을 “고품질 번역”이라고 부르지 않는다.

14. 번역본 보기로 전환

번역이 끝나도 사용자가 원문을 보고 있으면 완료되지 않은 흐름이다.

• target이 프로젝트 언어면 영어 번역본 보기로 Shelf 언어를 전환한다.
• Free target이 프로젝트 언어가 아니면 완료 카드의 현재 문서 번역 초안 열기로 생성된 파일을 연다.
• Shelf에서 번역본이 없는 문서는 번역 없음 상태를 확인하고 현재 원문을 유지한다.

번역본을 연 뒤 heading, link, code fence, table, front matter와 embedded asset 경로가 원문 구조와 일치하는지 확인한다.

저장되는 파일과 상태

state JSON을 복사해 번역을 완료된 것처럼 만들지 않는다. 경로, hash, prompt와 runtime identity가 맞지 않으면 재사용할 수 없고 검토 상태로 돌아간다.

문제 해결

기능별 실증 범위

완료 기준

• source, 현재 보기와 target locale의 차이를 설명할 수 있다.
• Free 현재 문서와 Pro Binder 범위를 구분했다.
• 관리형 로컬 runtime의 설치와 사용 가능 상태를 구분했다.
• 외부 provider의 전송 범위에 실행마다 동의했다.
• API key와 절대 로컬 경로가 문서·캡처·log에 남지 않았다.
• 용어 후보를 검토하고 필요한 항목만 저장했다.
• 번역 결과의 Markdown 구조와 링크를 확인했다.
• 수동 수정 보호, baseline 승인과 구간 재번역의 차이를 설명할 수 있다.
• 누락·변경·검토 필요·수동 수정 상태를 모두 확인했다.
• 번역 완료 뒤 실제 target 문서로 전환했다.

다음 단계는 AI 제안, 번역과 오디오의 오디오 경계에서 검토된 문서를 음성 자산으로 만드는 흐름으로 이어진다. 오디오 상세 장은 별도 실증 묶음으로 확장한다.