$ wikven translate mark --all
Wikven은 MediaWiki의 Translate 확장 기능을 사용하여 사이트를 두 개 이상의 언어로 빌드할 수 있습니다. Translate는 보통 번역자가 위키 내 편집기에서 작업하리라 기대하지만, 정적 빌드에는 그럴 공간이 없으므로 Wikven은 대신 소스 트리에서 이를 구동합니다. 다른 문서를 쓸 때와 똑같이, 파일을 추가하고 커밋하여 번역합니다.
번역 활성화하기
.wikven.yaml의 extensions에 Translate를 추가하고, Translate가 의존하는 UniversalLanguageSelector도 함께 추가합니다. 둘 다 Wikven 이미지에 번들되어 있으므로 설치할 것은 없습니다.
extensions:
- UniversalLanguageSelector
- Translate
정적 내보내기는 UniversalLanguageSelector의 런타임 웹폰트(라이브 엔드포인트에서 불러옴)를 제공할 수 없으므로, Wikven은 기본적으로 이를 끄고 독자는 각 문자를 자신의 시스템 글꼴로 보게 됩니다. 대신 WikvenBundleWebfonts를 설정하면 글꼴을 사이트에 구워 넣으므로, 어떤 문자의 글꼴이 없는 시스템의 독자도 의도한 서체를 볼 수 있습니다.
번역할 언어를 나열하지 않습니다. Translate 자체와 마찬가지로, 어떤 언어의 번역이 존재하는 순간 그 언어가 존재하게 됩니다. 문서를 작성하는 언어는 원본 언어로 유지됩니다.
번역할 문서 표시하기
문서에서 번역해야 할 부분을 <translate> 태그로 감싸고, 언어 막대를 두고 싶은 곳에 <languages/>를 추가하며, 각 단위에 <!--T:n--> 표시자를 붙입니다. 이는 Translate 자체의 문서 번역 마크업입니다:
<languages/>
<translate>
<!--T:1-->
{{SITENAME}} builds static sites from MediaWiki.
<!--T:2-->
It runs a real MediaWiki at build time.
</translate>
단위 번호를 손으로 매기지 않습니다. 내용을 <translate>로 감싸고 <languages/>를 추가한 다음, translate mark를 실행하여 <!--T:n--> 표시자를 삽입합니다. 이때 소스 디렉터리를 쓰기 가능하게 마운트합니다:
$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate mark --all
--all 대신 파일 하나를 전달하면 그 문서만 표시합니다. 표시는 멱등이며 안정적입니다. 이미 있는 번호는 유지하고 새 단위에 대해서만 표시자를 추가하므로, 내용을 추가할 때마다 다시 실행하면 됩니다. 번호는 단위의 정체성입니다. 번역은 이 번호를 참조하여 자신의 단위를 원본과 맞춥니다. 빌드는 언어 막대를 렌더링하고, 각 언어마다 Page/lang에 문서를 렌더링합니다.
번역 추가하기
번역은 문서 옆에 <Page>/<lang>.wikitext라는 이름으로 자리합니다. Intro.wikitext의 한국어 번역은 Intro/ko.wikitext입니다. translate scaffold로 그 골격을 생성하는데, 이는 모든 원본 단위에 대해 빈 <!--T:n--> 표시자를 쓰고 각 단위의 원본 텍스트를 안내로 나열합니다:
$ wikven translate scaffold ko Intro.wikitext
$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate scaffold ko Intro.wikitext
파일 대신 --all을 전달하면 번역할 수 있는 모든 문서의 골격을 생성합니다. 다시 실행해도 안전합니다. 번역해 둔 것은 유지하고 새 단위에 대한 표시자만 덧붙입니다.
그런 다음 각 단위의 번역을 그 표시자 아래에 채웁니다:
<!--T:1--> 위크벤은 미디어위키로 정적 사이트를 만듭니다. <!--T:2--> 빌드 시 실제 미디어위키를 실행합니다.
비워 둔 단위는 아직 번역되지 않은 것으로 간주됩니다. translate check가 이를 보고하고 빌드는 이를 원본 언어로 렌더링하므로, 한 문서를 한 번에 몇 단위씩 번역할 수 있습니다. @a1b2c3d4 스탬프는 (아래 참고) 손이 아니라 translate stamp가 추가합니다.
문서 제목 번역하기
문서의 제목도 하나의 단위이며, 예약된 표시자 <!--T:title-->를 씁니다. 이 단위만은 문서 위키텍스트의 일부가 아닙니다. 원본 텍스트가 문서 자신의 제목이므로, 원본 문서에는 아무것도 덧붙지 않고 원본 언어로 쓴 문서는 그대로 렌더링됩니다. 이는 Translate 자체의 문서 표시 제목이며, Wikven은 표시자만 더 짧게 씁니다.
번역한 제목은 번역 파일 맨 위, 번호가 붙은 단위들보다 앞에 씁니다. translate scaffold가 표시자를 두는 자리와 같습니다:
<!--T:title--> 소개 <!--T:1--> 위크벤은 미디어위키로 정적 사이트를 만듭니다.
그러면 번역된 문서는 Page/lang이라는 하위 문서 이름 대신 그 제목을 제목 머리글과 브라우저 탭에 보여 줍니다. 나머지는 달라지지 않습니다. translate check는 누락되었거나 오래된 제목을 다른 단위와 똑같이 보고하고, translate stamp는 제목에도 스탬프를 찍으며, 원본 문서의 이름을 바꾸면 문단을 고쳤을 때와 똑같이 모든 번역 제목이 오래된 상태가 됩니다.
예외는 DISPLAYTITLE 매직 워드로 자신의 제목을 직접 정하는 문서입니다. 이 매직 워드는 <translate> 밖에 있으므로 문서의 모든 번역본에 그대로 복사되어 모든 언어에서 같은 제목을 고정합니다. 그런 문서에는 번역할 제목 단위가 없습니다.
스탬프 찍기
번역을 마친 뒤 translate stamp를 실행하면, 최신 상태인 모든 단위가 자신이 일치하는 원본 버전을 기록합니다. 소스 디렉터리를 쓰기 가능하게 마운트합니다:
$ wikven translate stamp --all
$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate stamp --all
--all 대신 파일 하나를 전달하면 그 번역만 스탬프를 찍습니다.
번역을 최신으로 유지하기
원본 단위를 바꾸면 그 번역은 더 이상 스탬프와 일치하지 않아 오래된 상태가 됩니다. Wikven은 이를 숨기지 않습니다:
- 빌드된 사이트에서, 오래된 단위는 Translate를 구동하는 위키에서와 똑같이 오래된 번역으로 표시됩니다.
translate check는 오래되었거나 누락된 번역을 모두 경고로, 오류가 있는 원본 문서를 모두 오류로 보고합니다.--gate를 주면 오류에 대해서만 0이 아닌 코드로 종료하므로, 지속적 통합은 아무도 번역할 수 없는 문서에서는 실패하지만 단지 뒤처진 번역에서는 실패하지 않습니다:
$ wikven translate check --gate
::warning file=src/Intro/ko.wikitext::Stale translation unit T:2 (ko)
1 translation(s) out of date or missing.
$ docker run --rm -v "$PWD/src:/workspace/src" ghcr.io/chaotic-ground/wikven translate check --gate
::warning file=src/Intro/ko.wikitext::Stale translation unit T:2 (ko)
1 translation(s) out of date or missing.
check-translations 액션이 풀 리퀘스트에서 같은 검사를 실행하며, 각각을 해당 파일에 대한 주석으로 보고합니다. 오류가 있는 원본 문서에서는 빌드를 실패시키고 뒤처진 번역에서는 결코 실패시키지 않습니다. gate: false를 주면 오류가 있는 문서도 실패 없이 보고만 합니다. 이 문서 사이트가 이 방식으로 검사됩니다. 번역을 다시 최신으로 되돌리려면, 새 원본에 맞게 편집한 다음 translate stamp로 다시 스탬프를 찍습니다.