fixed #23: Add working example for generating pot/po files

sphinx-doc · May 12, 2019 · bac9242 · bac9242
1 parent 2c445f2
commit bac9242
Show file tree

Hide file tree

Showing 3 changed files with 253 additions and 7 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -20,6 +20,7 @@ Features
 Documentation
 -------------
 * #6: http://sphinx-intl.rtfd.io/
+* #23: Add working example for generating pot/po files
 
 Bug Fixes
 ---------

diff --git a/doc/conf.py b/doc/conf.py
@@ -25,5 +25,8 @@
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = 'sphinx_rtd_theme'
-# html_theme_options = {}
 
+# -- Options for sphinx-intl example
+
+locale_dirs = ['locale/']   # po files will be created in this directory
+gettext_compact = False     # optional: avoid file concatenation in sub directories.
diff --git a/doc/quickstart.rst b/doc/quickstart.rst
@@ -19,35 +19,277 @@ This section describe to translate with Sphinx_ and `sphinx-intl` command.
 
 1. Create your document by using Sphinx.
 
+   * working-example project is here:
+     https://github.com/sphinx-doc/sphinx-intl/tree/master/doc
+
 2. Add configurations to your `conf.py`::
 
       locale_dirs = ['locale/']   # path is example but recommended.
       gettext_compact = False     # optional.
 
    `locale_dirs` is required and `gettext_compact` is optional.
 
+   refs `example <https://github.com/sphinx-doc/sphinx-intl/blob/master/doc/conf.py#L29>`__.
+
 3. Extract document's translatable messages into pot files::
 
       $ make gettext
 
-4. Setup/Update your `locale_dir`::
+   This invoke the sphinx gettext builder that generates ``*.pot`` files under
+   ``_build/gettext`` directory.
+
+4. Setup/Update your po files under ``locale_dir``::
 
       $ sphinx-intl update -p _build/gettext -l de -l ja
 
-   Done. You got these directories that contain po files:
+   After this, you got these directories that contain po files:
 
    * `./locale/de/LC_MESSAGES/`
    * `./locale/ja/LC_MESSAGES/`
 
-5. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
+5. Translate your ``po`` files under `./locale/<lang>/LC_MESSAGES/`.
+
+6. Make translated document.
+
+   On Linux/BSD::
+
+      $ make -e SPHINXOPTS="-Dlanguage='ja'" html
 
-6. Build mo files and make translated document::
+   On Windows::
 
-      $ sphinx-intl build
-      $ make -e SPHINXOPTS="-D language='ja'" html
+      $ set SPHINXOPTS="-Dlanguage='ja'"
+      $ make html
 
 That's all!
 
 For more information, please refer :doc:`refs`.
 
 .. _Sphinx: http://sphinx-doc.org
+
+QuickStart console log
+----------------------
+
+::
+
+   (.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
+   loading translations ['ja']... not available for built-in messages
+   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']... not available for built-in messages
+   making output directory... done
+   building [mo]: targets for 0 po files that are out of date
+   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 English (code: en) ... 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
+