快速入门

安装

请使用 pip（8.1.1 或更高版本）安装 sphinx-intl。

$ pip install sphinx-intl

Sphinx 翻译的快速启动

本节描述了如何使用 Sphinx 和 sphinx-intl 命令进行翻译。

1. 通过使用 Sphinx 创建你的文件。

   • 工作实例项目在这里：https://github.com/sphinx-doc/sphinx-intl/tree/master/doc

2. 在你的 conf.py 中添加配置

   locale_dirs = ['locale/']   # path is example but recommended.
   gettext_compact = False     # optional.
   

   locale_dirs 是必需的，gettext_compact 是可选的。

   参考 example.

3. 将文件中的可翻译信息提取为 pot 文件

   $ make gettext
   

   这将调用 sphinx gettext builder，在 _build/gettext 目录下生成 *.pot 文件。

4. 在 locale_dir 下设置/更新你的 po 文件

   $ sphinx-intl update -p _build/gettext -l de -l ja
   

   在这之后，你会得到这些包含 po 文件的目录：

   • ./locale/de/LC_MESSAGES/

   • ./locale/ja/LC_MESSAGES/

5. 将你的 po 文件翻译到 ./locale/<lang>/LC_MESSAGES/。

6. 制作翻译文件。

   在 Linux/BSD 系统中:

   $ make -e SPHINXOPTS="-Dlanguage='ja'" html
   

   在 Windows 系统中:

   $ set SPHINXOPTS=-Dlanguage=ja
   $ make html
   

这就是全部！

更多信息，请参考 参考。

快速启动控制台日志

(.venv) C:/sphinx-intl/doc> pip install -r requirements.txt sphinx-intl
...

(.venv) C:/sphinx-intl/doc> tree /f
C:.
    authors.rst
    basic.rst
    changes.rst
    conf.py
    dev.rst
    index.rst
    make.bat
    Makefile
    quickstart.rst
    refs.rst
    requirements.txt

(.venv) C:/sphinx-intl/doc> make gettext
Running Sphinx v2.0.1
making output directory... done
building [gettext]: targets for 0 template files
building [gettext]: targets for 7 source files that are out of date
updating environment: 7 added, 0 changed, 0 removed
reading sources... [100%] refs
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] refs
writing message catalogs... [100%] refs
build succeeded.

The message catalogs are in _build/gettext.

(.venv) C:/sphinx-intl/doc> tree /f
C:.
│  authors.rst
│  basic.rst
│  changes.rst
│  conf.py
│  dev.rst
│  index.rst
│  make.bat
│  Makefile
│  quickstart.rst
│  refs.rst
│  requirements.txt
│
└─_build
    └─gettext
        │  authors.pot
        │  basic.pot
        │  changes.pot
        │  dev.pot
        │  index.pot
        │  quickstart.pot
        │  refs.pot
        │
        └─.doctrees

(.venv) C:/sphinx-intl/doc> sphinx-intl update -p _build/gettext -l de -l ja
Create: locale/de/LC_MESSAGES/authors.po
Create: locale/ja/LC_MESSAGES/authors.po
Create: locale/de/LC_MESSAGES/basic.po
Create: locale/ja/LC_MESSAGES/basic.po
Create: locale/de/LC_MESSAGES/changes.po
Create: locale/ja/LC_MESSAGES/changes.po
Create: locale/de/LC_MESSAGES/dev.po
Create: locale/ja/LC_MESSAGES/dev.po
Create: locale/de/LC_MESSAGES/index.po
Create: locale/ja/LC_MESSAGES/index.po
Create: locale/de/LC_MESSAGES/quickstart.po
Create: locale/ja/LC_MESSAGES/quickstart.po
Create: locale/de/LC_MESSAGES/refs.po
Create: locale/ja/LC_MESSAGES/refs.po

(.venv) C:/sphinx-intl/doc> tree /f
C:.
│  authors.rst
│  basic.rst
│  changes.rst
│  conf.py
│  dev.rst
│  index.rst
│  make.bat
│  Makefile
│  quickstart.rst
│  refs.rst
│  requirements.txt
│
├─locale
│  ├─de
│  │  └─LC_MESSAGES
│  │          authors.po
│  │          basic.po
│  │          changes.po
│  │          dev.po
│  │          index.po
│  │          quickstart.po
│  │          refs.po
│  │
│  └─ja
│      └─LC_MESSAGES
│              authors.po
│              basic.po
│              changes.po
│              dev.po
│              index.po
│              quickstart.po
│              refs.po
│
└─_build
    └─gettext
        │  authors.pot
        │  basic.pot
        │  changes.pot
        │  dev.pot
        │  index.pot
        │  quickstart.pot
        │  refs.pot
        │
        └─.doctrees

(.venv) C:/sphinx-intl/doc> # ================================
(.venv) C:/sphinx-intl/doc> # Edit po files for each languages
(.venv) C:/sphinx-intl/doc> # ================================

(.venv) C:/sphinx-intl/doc> set SPHINXOPTS=-Dlanguage=ja

(.venv) C:/sphinx-intl/doc> make html
Running Sphinx v2.0.1
loading translations [ja]... done
making output directory... done
building [mo]: targets for 7 po files that are out of date
writing output... [100%] locale/ja/LC_MESSAGES/refs.mo
building [html]: targets for 7 source files that are out of date
updating environment: 7 added, 0 changed, 0 removed
reading sources... [100%] refs
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] refs
generating indices... genindex
writing additional pages... searchc:/project/sphinx-dev/sphinx-intl/.venv/lib/site-packages/sphinx_rtd_theme/search.html:20: RemovedInSphinx30Warning: To modify script_fil
es in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
  {{ super() }}

copying static files... done
copying extra files... done
dumping search index in Japanese (code: ja) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

(.venv) C:/sphinx-intl/doc> tree /f
C:.
│  authors.rst
│  basic.rst
│  changes.rst
│  conf.py
│  dev.rst
│  index.rst
│  make.bat
│  Makefile
│  quickstart.rst
│  refs.rst
│  requirements.txt
│
├─locale
│  ├─de
│  │  └─LC_MESSAGES
│  │          authors.po
│  │          basic.po
│  │          changes.po
│  │          dev.po
│  │          index.po
│  │          quickstart.po
│  │          refs.po
│  │
│  └─ja
│      └─LC_MESSAGES
│              authors.po
│              basic.po
│              changes.po
│              dev.po
│              index.po
│              quickstart.po
│              refs.po
│
└─_build
    ├─doctrees
    │
    ├─gettext
    │  │  authors.pot
    │  │  basic.pot
    │  │  changes.pot
    │  │  dev.pot
    │  │  index.pot
    │  │  quickstart.pot
    │  │  refs.pot
    │  │
    │  └─.doctrees
    │
    └─html
        │  .buildinfo
        │  authors.html
        │  basic.html
        │  changes.html
        │  dev.html
        │  genindex.html
        │  index.html
        │  objects.inv
        │  quickstart.html
        │  refs.html
        │  search.html
        │  searchindex.js
        │
        ├─_sources
        └─_static