From 5ddbabdcd45baa716450f8d39e2e1c3f9538f3f2 Mon Sep 17 00:00:00 2001 From: "Leonardo J. Caballero G" Date: Tue, 17 Apr 2018 19:21:14 -0400 Subject: [PATCH] Added more details informations about translations guide --- docs/translations.rst | 195 ++++++++++++++++++++++++++++++------------ 1 file changed, 141 insertions(+), 54 deletions(-) diff --git a/docs/translations.rst b/docs/translations.rst index 459e28d8..281e8ea3 100644 --- a/docs/translations.rst +++ b/docs/translations.rst @@ -21,6 +21,32 @@ For translating the Read the Docs Sphinx Theme you will need to install the foll $ pip install babel Jinja2 +If the command has been correctly installed, a command should allow you to use the following command: + +.. code:: bash + + $ pybabel subcommand options + +More options about this commands, execute the following command: + +.. code:: bash + + $ pybabel --help + Usage: pybabel command [options] [args] + + Options: + --version show program's version number and exit + -h, --help show this help message and exit + --list-locales print all known locales and exit + -v, --verbose print as much as possible + -q, --quiet print as little as possible + + commands: + compile compile message catalogs to MO files + extract extract messages from source files and generate a POT file + init create new message catalogs from a POT file + update update existing message catalogs from a POT file + Translating Applications with Babel ----------------------------------- @@ -54,19 +80,25 @@ The translations files are based on ``gettext`` format and they are placed at th .. code:: bash - sphinx_rtd_theme/locale/ - ├── es - │   └── LC_MESSAGES - │   ├── sphinx.mo - │   └── sphinx.po - └── sphinx.pot + sphinx_rtd_theme/locale/ + ├── es + │   └── LC_MESSAGES + │   ├── sphinx.mo + │   └── sphinx.po + └── sphinx.pot -- The :file:`sphinx.pot` file, is the **Portable Object Template** Gettext format. +:file:`sphinx_rtd_theme/locale//LC_MESSAGES/` + This folder contains a specific language is the **Gettext format**. -- The :file:`sphinx.po` file, is the **Portable Object** Gettext format to translate. +:file:`sphinx.pot` + This file is the **Portable Object Template** Gettext format. -- The :file:`sphinx.mo` file, is the **Machine Object** Gettext format generated later of translate - your :file:`sphinx.po` file via the catalog compilation. +:file:`sphinx.po` + This file is the **Portable Object** Gettext format to translate. + +:file:`sphinx.mo` + This file is the **Machine Object** Gettext format generated later of translate + your :file:`sphinx.po` file via the catalog compilation. Babel Configurations -------------------- @@ -81,33 +113,92 @@ at root folder of this Sphinx theme, look like the following: .. code:: cfg - [bdist_wheel] - universal = 1 + [bdist_wheel] + universal = 1 - # Babel configurations for setup.py scripts - [compile_catalog] - domain = sphinx - directory = sphinx_rtd_theme/locale/ + # Babel configurations for setup.py scripts + [compile_catalog] + domain = sphinx + directory = sphinx_rtd_theme/locale/ - [extract_messages] - mapping_file = babel.cfg - output_file = sphinx_rtd_theme/locale/sphinx.pot - keywords = _ l_ lazy_gettext + [extract_messages] + mapping_file = babel.cfg + output_file = sphinx_rtd_theme/locale/sphinx.pot + keywords = _ l_ lazy_gettext - [init_catalog] - input_file = sphinx_rtd_theme/locale/sphinx.pot - output_file = sphinx_rtd_theme/locale/$LANG/LC_MESSAGES/sphinx.po + [init_catalog] + input_file = sphinx_rtd_theme/locale/sphinx.pot + output_file = sphinx_rtd_theme/locale/$LANG/LC_MESSAGES/sphinx.po - [update_catalog] - domain = sphinx - input_file = sphinx_rtd_theme/locale/sphinx.pot - output_dir = sphinx_rtd_theme/locale/ + [update_catalog] + domain = sphinx + input_file = sphinx_rtd_theme/locale/sphinx.pot + output_dir = sphinx_rtd_theme/locale/ + +If the command has been correctly installed or registered, a project's setup.py script should +allow you to use the following command: + +.. code:: bash + + $ python ./setup.py subcommand options + +More options about this commands, execute the following command: + +.. code:: bash + + $ python ./setup.py --help-commands + Standard commands: + build build everything needed to install + build_py "build" pure Python modules (copy to build directory) + build_ext build C/C++ extensions (compile/link to build directory) + build_clib build C/C++ libraries used by Python extensions + build_scripts "build" scripts (copy and fixup #! line) + clean clean up temporary files from 'build' command + install install everything from build directory + install_lib install all Python modules (extensions and pure Python) + install_headers install C/C++ header files + install_scripts install scripts (Python or otherwise) + install_data install data files + sdist create a source distribution (tarball, zip file, etc.) + register register the distribution with the Python package index + bdist create a built (binary) distribution + bdist_dumb create a "dumb" built distribution + bdist_rpm create an RPM distribution + bdist_wininst create an executable installer for MS Windows + upload upload binary package to PyPI + check perform some checks on the package + + Extra commands: + saveopts save supplied options to setup.cfg or other config file + compile_catalog compile message catalogs to binary MO files + develop install package in 'development mode' + upload_docs Upload documentation to PyPI + extract_messages extract localizable strings from the project code + init_catalog create a new catalog based on a POT file + test run unit tests after in-place build + update_catalog update message catalogs from a POT file + setopt set an option in setup.cfg or another config file + install_egg_info Install an .egg-info directory for the package + rotate delete older distributions, keeping N newest files + bdist_wheel create a wheel distribution + egg_info create a distribution's .egg-info directory + alias define a shortcut to invoke one or more commands + easy_install Find/get/install Python packages + bdist_egg create an "egg" distribution + dist_info create a .dist-info directory + build_sphinx Build Sphinx documentation + + usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...] + or: setup.py --help [cmd1 cmd2 ...] + or: setup.py --help-commands + or: setup.py cmd --help .. seealso:: + More details check out the following links: - - `Writing the Setup Configuration File `_. - - `How setup this file for babel configurations `_. + - `Writing the Setup Configuration File `_. + - `How setup this file for babel configurations `_. Extraction Configurations ------------------------- @@ -118,18 +209,19 @@ For typical Sphinx extensions, this is what you want in there: .. code:: cfg - # Extraction from Jinja2 HTML templates - [jinja2: **/**.html] - encoding = utf-8 - ignore_tags = script,style - include_attrs = alt title summary placeholder + # Extraction from Jinja2 HTML templates + [jinja2: **/**.html] + encoding = utf-8 + ignore_tags = script,style + include_attrs = alt title summary placeholder .. seealso:: + More details check out the following links: - - `How setup this file `_ - - `A previous file example description `_ + - `How setup this file `_ + - `A previous file example description `_ Administrative Tasks ==================== @@ -146,23 +238,21 @@ Extract messages It can extract localizable messages from a variety of difference source files, and generate a PO (portable object) template file from the collected messages. -Running the command will produce a PO template file: +Running the following command will produce a PO template file: .. code:: bash $ python ./setup.py extract_messages -o ./sphinx_rtd_theme/locale/sphinx.pot -.. $ python ./setup.py extract_messages --output-file ./sphinx_rtd_theme/locale/sphinx.pot - .. tip:: + More options please, check out http://babel.pocoo.org/en/latest/setup.html#extract-messages Init catalog ------------ -It creates a new translation catalog based on a PO template file (POT). - -Running the command will produce a PO file: +It creates a new translation catalog based on a PO template file (POT). Running the following +command will produce a PO file: .. code:: bash @@ -171,14 +261,14 @@ Running the command will produce a PO file: creating catalog './sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po' based on './sphinx_rtd_theme/locale/sphinx.pot' .. tip:: + More options please, check out http://babel.pocoo.org/en/latest/setup.html#init-catalog Update catalog -------------- -It updates an existing translations catalog based on a PO template file (POT). - -Running the following command will update a PO file: +It updates an existing translations catalog based on a PO template file (POT). Running the following +command will update a PO file: .. code:: bash @@ -187,30 +277,26 @@ Running the following command will update a PO file: updating catalog ./sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po based on ./sphinx_rtd_theme/locale/sphinx.pot .. tip:: + More options please, check out http://babel.pocoo.org/en/latest/setup.html#update-catalog Compile catalog --------------- -For compile catalog of the theme's project-wide is available. - -If the command has been correctly installed or registered, a -project's setup.py script should allow you to use the command: +It compile catalog an existing translations based on PO files into MO files. Running the following +command will compile catalog of PO files: .. code:: bash $ python ./setup.py compile_catalog -d ./sphinx_rtd_theme/locale/ -l es running compile_catalog -.. $ python ./setup.py compile_catalog --directory ./sphinx_rtd_theme/locale/ --locale es - running compile_catalog compiling catalog ./sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po to ./sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.mo Statistics about translations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For to print the statistics about the theme translations from his catalog. - -Running the following command will printing the statistics: +For to print the statistics about the theme translations from his catalog. Running the following +command will printing the statistics: .. code:: bash @@ -220,4 +306,5 @@ Running the following command will printing the statistics: compiling catalog sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.po to sphinx_rtd_theme/locale/es/LC_MESSAGES/sphinx.mo .. tip:: + More options for ``compile`` sub-command, please, check out http://babel.pocoo.org/en/latest/cmdline.html#compile