国際化¶
構造を保って説明を翻訳します。Guidedog はメッセージを抽出し、翻訳をマージして指定言語でビルドします。原文を基準とし、訳がない場合は文章を作らず原文に戻します。
作業の流れ¶
-
gettextビルダーでメッセージテンプレートを作ります。guidedog build gettext
_build/gettextに、テキストドメインごとのテンプレート（.pot）を書き出す。段落、見出し、リスト項目、表のセル、キャプション、注意書き、用語、フィールドがメッセージになる。出典のファイルと行番号も記録される。 -
sphinx-intl updateと同様に、各言語のカタログを作成・更新します。guidedog intl update -l de -l fr
カタログは
locales/de/LC_MESSAGES/*.poに作られる。次回以降はmsgmergeと同様に新しいテンプレートをマージする。訳文は保持され、原文が変わったものは fuzzy として確認対象になる。文書から消えたメッセージは末尾に廃止項目（#~）として残り、再登場したときに訳を復元できる。 -
各
msgstrを訳文で埋めます。確認が済んだらそのメッセージの#, fuzzyを削除します。fuzzy な訳文は使いません。msgid "Hello *world*, see the site_." msgstr "Hallo *Welt*, siehe site_."
-
sphinx-intl statと同様に翻訳の進捗を確認します。guidedog intl stat -l de
-
指定言語でビルドします。
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 から、次の順に検索する。
- プロジェクトの
locales/LANGUAGE/LC_MESSAGES/guidedog.po。 - Sphinx と同じく、プロジェクトの
locales/LANGUAGE/LC_MESSAGES/sphinx.po。 - 組み込みカタログはドイツ語、スペイン語、フランス語、日本語、ブラジルポルトガル語、ロシア語、簡体字中国語に対応します。
メッセージIDは英語で、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）を設定すると、どのマシンでも同じ日付で再現可能なビルドになる。