Guidedog 설명서 0.2.0
언어
이 페이지의 내용
Guidedog / 문서 0.2.0

국제화

구조를 유지하며 설명을 번역하세요. Guidedog는 메시지 카탈로그를 추출하고 번역을 병합하여 선택한 언어로 빌드합니다. 원문이 기준이며, 누락된 번역은 내용을 만들어 내지 않고 원문으로 돌아갑니다.

작업 흐름

  1. gettext 빌더로 메시지 템플릿을 만드세요.

    guidedog build gettext

    _build/gettext에 텍스트 도메인별 템플릿(.pot)을 만든다. 문서의 모든 문단, 제목, 목록 항목, 표 셀, 캡션, 알림, 용어, 필드가 메시지가 된다. 원본 파일과 줄 번호도 함께 기록된다.

  2. sphinx-intl update처럼 언어별 카탈로그를 만들거나 갱신하세요.

    guidedog intl update -l de -l fr

    카탈로그는 locales/de/LC_MESSAGES/*.po에 생성된다. 다시 실행하면 msgmerge처럼 새 템플릿을 병합한다. 기존 번역은 유지하고, 원문이 바뀐 번역은 검토하도록 fuzzy로 표시한다. 문서에서 사라진 메시지는 끝에 사용 중단 항목(#~)으로 남겨 두어 나중에 번역을 복원할 수 있다.

  3. 각 msgstr에 번역을 넣으세요. 번역이 맞는지 확인한 뒤 #, fuzzy 줄을 지우세요. fuzzy 번역은 사용하지 않습니다.

    msgid "Hello *world*, see the site_."
msgstr "Hallo *Welt*, siehe site_."

  4. sphinx-intl stat처럼 번역 진행 상황을 확인하세요.

    guidedog intl stat -l de

  5. 해당 언어로 빌드하세요.

    guidedog build html -D language=de
guidedog build pdf -D language=de

    또는 conf.toml에서 language = "de"를 설정하세요.

    책 파일 이름에는 언어 접미사가 붙는다. manual.pdf는 manual-de.pdf가 된다. 빌드마다 완전한 출력 세대를 게시하므로 여러 판을 보관할 때는 대상 폴더를 따로 쓴다. 예를 들어 독일어는 guidedog build -b pdf docs build/books/de -D language=de, 영어는 guidedog build -b pdf docs build/books/en -D language=en으로 만든다.

다른 입력과 마찬가지로 카탈로그가 바뀐 문서만 다시 읽습니다. 카탈로그를 추가하거나 지우면 모든 문서를 다시 읽습니다.

guidedog intl은 sphinx-intl의 옵션을 받는다. -p DIR은 템플릿 위치(기본 _build/gettext), 반복 가능한 -l LANG은 언어(기본 프로젝트 언어), -d DIR은 카탈로그 위치(기본 locale_dirs의 첫 항목), -w N은 줄 너비(기본 76)이다. --no-obsolete도 지원한다.

번역 작성

메시지는 마크업을 포함한 단락, 제목, 기타 요소의 원문입니다. .rst는 reStructuredText, .md는 Markdown입니다. 번역도 같은 문법으로 읽으므로 원문처럼 강조, 링크, 참조를 쓸 수 있습니다.

참조는 그대로 유지해야 합니다. 모든 참조의 표기를 보존하고, 주변 텍스트와 표시 제목만 바꿀 수 있습니다.

msgid "See :ref:`install` and the site_."
msgstr "Siehe :ref:`Installation <install>` und die site_."

번역에서 참조가 빠지면 Sphinx처럼 경고(inconsistent references in translated message)를 내고 번역을 사용한다. 원문에 없는 참조를 추가하면 이를 해결할 수 없어 경고와 함께 원문을 유지한다. 리더가 번역의 마크업을 거부할 때도 원문을 유지하고 경고에 해당 번역을 표시한다.

절의 앵커는 언어에 따라 바뀌지 않습니다. 번역된 제목도 원문의 앵커를 유지하므로 내부·외부 링크가 계속 동작합니다.

설정

표준 설정은 Sphinx의 이름과 기본값을 따릅니다. Guidedog는 번역하지 않을 참조 부록을 위한 추출 전용 제외 설정도 제공합니다.

설정 의미
language 빌드할 언어입니다. 예: "de", "pt_BR".
locale_dirs 소스 폴더 기준 카탈로그 위치다. 각 위치에 LANGUAGE/LC_MESSAGES/DOMAIN.po(또는 컴파일한 .mo)를 둔다. 기본값은 ["locales"]이다. 여러 위치가 있으면 해당 메시지를 번역하는 첫 카탈로그를 사용한다.
gettext_compact 문서 메시지가 들어갈 카탈로그를 정한다. true(기본값)이면 최상위 문서는 각각 하나를 쓰고 같은 폴더의 문서는 공유한다(guide/usage.rst는 guide.po). false이면 문서마다 하나를 만든다. 이름을 지정하면 모든 문서가 그 이름의 카탈로그를 쓴다.
gettext_location 메시지 위치(#: ../../index.rst:12)를 기록합니다. 기본값은 true입니다.
gettext_uuid 메시지가 나타나는 곳마다 식별자를 기록합니다. 문서, 메시지, 출현 위치로 만들므로 빌드마다 같습니다.
gettext_auto_build 각 .po를 옆의 .mo로 컴파일하여 다른 도구에서 쓰게 합니다. 기본값은 true입니다. Guidedog는 .po를 직접 읽습니다.
gettext_additional_targets 추가 번역 대상: index(색인 항목), literal-block, doctest-block, raw, image(대체 텍스트).
gettext_allow_fuzzy_translations fuzzy 번역도 사용합니다. 기본값은 false입니다.
gettext_exclude_patterns POT 추출에서만 제외하는 문서 경로 패턴입니다. 예: ["api/**"]. 기본값은 []이며, 문서는 HTML과 PDF에 남습니다.
gettext_last_translator, gettext_language_team 템플릿 헤더의 Last-Translator와 Language-Team.
figure_language_filename 빌드 언어에 맞는 이미지 파일이다. 기본값은 "{root}.{language}{ext}"이다. language = "de"이면 파일이 있을 때 img/logo.png 대신 img/logo.de.png를 쓴다. 필드는 {root}, {path}, {basename}, {ext}, {docpath}, {language}이다.
translation_progress_classes 번역된 요소에는 translated, 나머지에는 untranslated 클래스를 붙인다(true). 둘 중 하나만 붙일 수도 있다("translated" 또는 "untranslated"). 스타일시트로 남은 부분을 표시할 수 있다.

Guidedog의 인터페이스 문구

Guidedog 자체도 알림 제목, "Added in version 2.1", "Fig. 1", "Contents", 레이아웃의 "Previous", "Next", "Navigation", "Search", 검색·색인 페이지, 책의 "Version" 같은 문구를 만든다. 이 문구는 guidedog 텍스트 도메인에서 다음 순서로 찾는다.

  1. 프로젝트의 locales/LANGUAGE/LC_MESSAGES/guidedog.po.
  2. Sphinx처럼 프로젝트의 locales/LANGUAGE/LC_MESSAGES/sphinx.po.
  3. Guidedog 내장 카탈로그는 독일어, 스페인어, 프랑스어, 일본어, 브라질 포르투갈어, 러시아어, 중국어 간체를 지원합니다.

메시지 식별자는 영어다. Sphinx에 같은 문구가 있으면 식별자도 같으므로 프로젝트의 sphinx.po를 계속 쓸 수 있다. 자체 guidedog.po로 문구를 바꾸거나 언어를 추가할 수 있다.

템플릿은 Sphinx처럼 _(), gettext(), ngettext()로 번역합니다.

<small>{{ _('Previous') }}</small>
{{ _('Last updated on %s.')|format(last_updated) }}

conf.toml에서 지정하지 않으면 numfig_format, html_title, html_short_title는 언어를 따릅니다.

날짜

|today|, 책의 날짜, 페이지의 last_updated는 Sphinx와 같은 규칙을 쓴다. today_fmt와 html_last_updated_fmt는 strftime 형식이고 월·요일 이름은 language를 따른다. %b %d, %Y는 영어로 "Sep 29, 2026", 독일어로 "Sept. 29, 2026"이다. 빈 형식은 _('%b %d, %Y')이며 카탈로그에서 번역할 수 있다. 앞서 나열한 언어의 이름은 Unicode CLDR에서 가져온다. 다른 언어는 Babel이 모르는 언어에 대한 Sphinx처럼 영어를 사용한다.

날짜는 현지 시간대의 날짜다. SOURCE_DATE_EPOCH(1970년부터의 초, UTC)을 설정하면 모든 컴퓨터에서 같은 날짜로 재현 가능한 빌드를 할 수 있다.