...
 
Commits (28)
language: python
python:
- "3.7"
- "3.6"
- "3.5"
- "3.4"
- "2.7"
matrix:
exclude:
- python: "3.7"
- python: "3.6"
- python: "3.5"
- python: "3.4"
- python: "2.7"
include:
- python: "3.6"
- python: "3.7"
dist: xenial # required for Python >= 3.7 (travis-ci/travis-ci#9069)
env: TOXENV=flake8
- python: "3.6"
- python: "3.7"
dist: xenial # required for Python >= 3.7 (travis-ci/travis-ci#9069)
env: TOXENV=sdist
- python: "3.7"
dist: xenial # required for Python >= 3.7 (travis-ci/travis-ci#9069)
env: TOXENV=py37
- python: "3.6"
env: TOXENV=py36
- python: "3.5"
env: TOXENV=py35
- python: "3.4"
env: TOXENV=py34
- python: "2.7"
env: TOXENV=py27
install:
......
=======
AUTHORS
=======
* Takayuki Shimizukawa <https://github.com/shimizukawa>
* Takeshi Komiya <https://github.com/tk0miya>
Original
--------
This utility derived from these projects.
* https://bitbucket.org/tk0miya/sphinx-gettext-helper
* https://bitbucket.org/shimizukawa/sphinx-transifex
......@@ -2,21 +2,57 @@
CHANGES
=======
0.9.12 (unreleased)
1.0.0 (2019/05/12)
===================
Environments
------------
* Adopt to semver_
.. _semver: https://semver.org/spec/v2.0.0.html
Incompatibility
---------------
Features
--------
Documentation
-------------
* #6: http://sphinx-intl.rtfd.io/
* #23: Add working example for generating pot/po files
Bug Fixes
---------
0.9.12 (2019/05/12)
===================
Environments
------------
- Drop supporting Python-3.4
- Add supporting Python-3.7.
#25: Python-3.7 introduce ``__dir__`` module function by :pep:`562`, so the
attribute must not override for another purpose. Thanks to Julien Enselme.
Incompatibility
---------------
* #27: `settings` resource name will be renamed to `settings_` on Transifex.
Thanks to Anthony.
Features
--------
* #28,#29: Add option `'-w', '--line-width'` for the maximum line width of PO files.
Thanks to Armand Ciejak.
Documentation
-------------
- #22: ```_build/locale`` (for old sphinx) -> ``_build/gettext`` (for current sphinx)
Bug Fixes
---------
......@@ -32,7 +68,10 @@ Incompatibility
Features
--------
* #17,#18: Adding --tag -t option, to pass tags from arguments to conf.py. Thanks to
* #17,#18: Adding --tag -t option, to pass tags from arguments to conf.py.
to
Claudio Alarcon-Reyes.
Documentation
......@@ -48,7 +87,7 @@ Bug Fixes
Environments
------------
* Drop supporting Python-3.3 and 2.6
- Add supporting Python-3.6
* Add supporting Python-3.6
Bug Fixes
---------
......@@ -84,7 +123,7 @@ Environments
Incompatibility
---------------
* 'glossary' resource name will be renamed to 'glossary_' on Transifex.
* `glossary` resource name will be renamed to `glossary_` on Transifex.
Since Aug 2015, Transifex reject 'glossary' resource name because the slug is reserved.
Features
......
By contributing you agree to abide by the `Contributor Code of Conduct`_.
.. _Contributor Code of Conduct: https://www.contributor-covenant.org/version/1/4/code-of-conduct
Report Issue
------------
**To Be Written**
* https://github.com/sphinx-doc/sphinx-intl/issues
Pull Request
------------
**To Be Written**
* https://github.com/sphinx-doc/sphinx-intl/pulls
License for Sphinx
==================
BSD 2-Clause License
Copyright (c) 2013 by Takayuki SHIMIZUKAWA.
Copyright (c) 2019, Sphinx team
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
======================================================
===================================================
sphinx-intl: translation support utility for Sphinx
======================================================
===================================================
.. image:: https://travis-ci.org/sphinx-doc/sphinx-intl.svg?branch=master
:target: https://travis-ci.org/sphinx-doc/sphinx-intl
`sphinx-intl` is a utility tool that provides several features that make it
``sphinx-intl`` is a utility tool that provides several features that make it
easy to translate and to apply translation to Sphinx_ generated document.
Optional: support the Transifex service for translation with Sphinx_ .
.. _Sphinx: http://sphinx-doc.org
.. contents::
:local:
QuickStart for sphinx translation
===================================
This section describe to translate with Sphinx_ and `sphinx-intl` command.
1. Create your document by using Sphinx.
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.
3. Extract document's translatable messages into pot files::
$ make gettext
4. Setup/Update your `locale_dir`::
$ sphinx-intl update -p _build/locale -l de -l ja
Done. 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/`.
6. Build mo files and make translated document::
$ sphinx-intl build
$ make -e SPHINXOPTS="-D language='ja'" html
That's all!
Basic Features
===============
* create or update po files from pot files.
* build mo files from po files.
Requirements for basic
-----------------------
- Python 3.6, 3.5, 3.4, 2.7, pypy.
- external library: setuptools_, six_, babel_, click_
Optional features
==================
These features need `transifex-client`_ library.
* create .transifexrc file from environment variable, without interactive
input.
* create .tx/config file without interactive input.
* update .tx/config file from locale/pot files automatically.
* build mo files from po files in the locale directory.
You need to use `tx` command for below features:
.. image:: https://img.shields.io/readthedocs/sphinx-intl/master.svg
:alt: Read the Docs (master)
:target: http://sphinx-intl.rtfd.io/
* `tx push -s` : push pot (translation catalogs) to transifex.
* `tx pull -l ja` : pull po (translated catalogs) from transifex.
.. image:: https://img.shields.io/pypi/v/sphinx-intl.svg
:alt: PyPI
:target: http://pypi.org/p/sphinx-intl
Requirements for optional
--------------------------
.. image:: https://img.shields.io/pypi/pyversions/sphinx-intl.svg
:alt: PyPI - Python Version
- Your transifex_ account if you want to download po files from transifex
or you want to translate on transifex.
.. image:: https://img.shields.io/github/license/sphinx-doc/sphinx-intl.svg
:alt: License
:target: https://github.com/sphinx-doc/sphinx-intl/blob/master/LICENSE
- external library: `transifex-client`_
.. image:: https://img.shields.io/travis/sphinx-doc/sphinx-intl/master.svg
:alt: Travis (.org) branch
:target: https://travis-ci.org/sphinx-doc/sphinx-intl
.. image:: https://img.shields.io/github/stars/sphinx-doc/sphinx-intl.svg?style=social&label=Stars
:alt: GitHub stars
:target: https://github.com/sphinx-doc/sphinx-intl
Installation
Documentation
=============
Recommend strongly: use virtualenv for this procedure::
$ pip install sphinx-intl
If you want to use `Optional Features`_, you need install additional library::
$ pip install sphinx-intl[transifex]
Commands, options, environment variables
=========================================
Commands
--------
Type `sphinx-intl` without arguments, options to show command help.
Setup environment variables
---------------------------
All command-line options can be set with environment variables using the
format SPHINXINTL_<UPPER_LONG_NAME> . Dashes (-) have to replaced with
underscores (_).
For example, to set the languages::
export SPHINXINTL_LANGUAGE=de,ja
This is the same as passing the option to sphinx-intl directly::
sphinx-intl <command> --language=de --language=ja
Setup sphinx conf.py
---------------------
Add below settings to sphinx document's conf.py if not exists::
locale_dirs = ['locale/'] #for example
gettext_compact = False #optional
Setup Makefile / make.bat
-------------------------
`make gettext` will generate pot files into `_build/locale` directory,
however pot files should be generated in the `locale/pot` is convenient.
You can be done by replacing `_build/locale` with `locale/pot` in your
`Makefile` and/or `make.bat` that was generated by sphinx-quickstart.
- http://sphinx-intl.rtfd.io/
License
=======
Licensed under the BSD license.
See the LICENSE file for specific terms.
Original
========
This utilty derived from these projects.
* https://bitbucket.org/tk0miya/sphinx-gettext-helper
* https://bitbucket.org/shimizukawa/sphinx-transifex
CHANGES
=======
See: https://github.com/sphinx-doc/sphinx-intl/blob/master/CHANGES
.. _Sphinx: http://sphinx-doc.org
.. _transifex: https://transifex.com
.. _transifex-client: https://pypi.python.org/pypi/transifex-client
.. _setuptools: https://pypi.python.org/pypi/setuptools
.. _six: https://pypi.python.org/pypi/six
.. _babel: https://pypi.python.org/pypi/babel
.. _click: https://pypi.python.org/pypi/click
=======================
Testing for sphinx-intl
=======================
First, you need install testing tools::
pip install -r requirements-testing.txt
And run::
tox
.. note::
sphinx-intl using travis-ci service to test for all environments.
https://travis-ci.org/sphinx-doc/sphinx-intl
.. release procedure
Procedure:
1. check travis-ci testing result: https://travis-ci.org/sphinx-doc/sphinx-intl
2. update release version/date in ``sphinx_intl/__init__.py`` and ``CHANGES.rst``
3. ``python setup.py release sdist bdist_egg``
4. check PyPI page: https://pypi.org/p/sphinx-intl
5. tagging with version name that MUST following semver. e.g.: ``git tag 1.0.1``
6. ``git push --tags`` to push tag
7. bump version in ``CHANGES.rst`` and commit/push them onto GitHub
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = sphinx-intl
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
.. include:: ../AUTHORS.rst
=====
Basic
=====
.. contents::
:local:
Basic Features
===============
* create or update po files from pot files.
* build mo files from po files.
Optional features
==================
These features depends to `transifex-client`_ library.
Please refer Installation_ section to install it.
* create ``.transifexrc`` file from environment variable, without interactive
input.
* create ``.tx/config`` file without interactive input.
* update ``.tx/config`` file from locale/pot files automatically.
* build mo files from po files in the locale directory.
You need to use `tx` command for below features:
* ``tx push -s`` : push pot (translation catalogs) to transifex.
* ``tx pull -l ja`` : pull po (translated catalogs) from transifex.
.. _transifex-client: https://pypi.python.org/pypi/transifex-client
Installation
=============
Recommend strongly: use virtualenv/venv for this procedure::
$ pip install sphinx-intl
If you want to use `Optional Features`_, you need install additional library::
$ pip install sphinx-intl[transifex]
.. include:: ../CHANGES.rst
# -*- coding: utf-8 -*-
from sphinx_intl import __version__
# -- Project information -----------------------------------------------------
project = 'sphinx-intl'
copyright = 'Sphinx team'
author = 'Sphinx team'
version = release = __version__
# -- General configuration ---------------------------------------------------
extensions = [
]
source_suffix = '.rst'
master_doc = 'index'
language = None
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_rtd_theme'
# -- 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.
===========
Development
===========
Code of Conduct
===============
.. include:: ../CODE_OF_CONDUCT.rst
Contribution Guideline
======================
.. include:: ../CONTRIBUTING.rst
Setup development environment
=============================
* Requires supported Python version
* do setup under sphinx-intl.git repository root as::
$ pip install -U pip setuptools wheel setuptools_scm
$ pip install -r requirements-testing.txt
Testing
=======
Tests with supported python version that are in:
* ``setup.py``
* ``tox.ini``
* ``.travis.yml``
Run test
--------
Just run tox::
$ tox
tox have several sections for testing.
CI (Continuous Integration)
----------------------------
All tests will be run on Travis CI service.
* https://travis-ci.org/sphinx-doc/sphinx-intl
Releasing
=========
New package version
-------------------
The sphinx-intl package will be uploaded to PyPI: https://pypi.org/project/sphinx-intl/.
Here is a release procefure for releasing.
.. include:: ../checklist.rst
Updated documentation
---------------------
Sphinx documentation under ``doc/`` directory on the master branch will be automatically uploaded into ReadTheDocs: http://sphinx-intl.rtfd.io/.
===================================================
sphinx-intl: translation support utility for Sphinx
===================================================
``sphinx-intl`` is a utility tool that provides several features that make it
easy to translate and to apply translation to Sphinx_ generated document.
Optional: support the Transifex service for translation with Sphinx_ .
.. _Sphinx: http://sphinx-doc.org
.. image:: https://img.shields.io/readthedocs/sphinx-intl/master.svg
:alt: Read the Docs (master)
:target: http://sphinx-intl.rtfd.io/
.. image:: https://img.shields.io/pypi/v/sphinx-intl.svg
:alt: PyPI
:target: http://pypi.org/p/sphinx-intl
.. image:: https://img.shields.io/pypi/pyversions/sphinx-intl.svg
:alt: PyPI - Python Version
.. image:: https://img.shields.io/github/license/sphinx-doc/sphinx-intl.svg
:alt: License
:target: https://github.com/sphinx-doc/sphinx-intl/blob/master/LICENSE
.. image:: https://img.shields.io/travis/sphinx-doc/sphinx-intl/master.svg
:alt: Travis (.org) branch
:target: https://travis-ci.org/sphinx-doc/sphinx-intl
.. image:: https://img.shields.io/github/stars/sphinx-doc/sphinx-intl.svg?style=social&label=Stars
:alt: GitHub stars
:target: https://github.com/sphinx-doc/sphinx-intl
Documentation
=============
- http://sphinx-intl.rtfd.io/
License
=======
Licensed under the BSD license.
Contents
========
.. toctree::
quickstart
basic
refs
dev
authors
.. toctree::
:maxdepth: 2
changes
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
set SPHINXPROJ=sphinx-intl
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd
===========
Quick Start
===========
Installation
============
Please install sphinx-intl with using pip (8.1.1 or later).
.. code-block:: bash
$ pip install sphinx-intl
QuickStart for sphinx translation
===================================
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
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
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/`.
6. Make translated document.
On Linux/BSD::
$ make -e SPHINXOPTS="-Dlanguage='ja'" html
On Windows::
$ 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
==========
References
==========
.. contents::
:local:
Commands
========
Type `sphinx-intl` without arguments, options to show command help.
Environment Variables
=====================
All command-line options can be set with environment variables using the
format SPHINXINTL_<UPPER_LONG_NAME> . Dashes (-) have to replaced with
underscores (_).
For example, to set the languages::
export SPHINXINTL_LANGUAGE=de,ja
This is the same as passing the option to sphinx-intl directly::
sphinx-intl <command> --language=de --language=ja
Sphinx conf.py
==============
Add below settings to sphinx document's conf.py if not exists::
locale_dirs = ['locale/'] #for example
gettext_compact = False #optional
Makefile / make.bat
===================
`make gettext` will generate pot files into `_build/gettext` directory,
however pot files should be generated in the `locale/pot` is convenient.
You can be done by replacing `_build/gettext` with `locale/pot` in your
`Makefile` and/or `make.bat` that was generated by sphinx-quickstart.
sphinx
sphinx_rtd_theme
-e.[transifex,test]
-rrequirements-testing.txt
twine
wheel
# -*- coding: utf-8 -*-
from __future__ import with_statement
from setuptools import setup, find_packages
import os
......@@ -36,20 +34,25 @@ setup(
description=description,
long_description=README,
classifiers=[
"Development Status :: 4 - Beta",
"Environment :: Other Environment",
"Development Status :: 5 - Production/Stable",
"Environment :: Console",
"License :: OSI Approved :: BSD License",
"Topic :: Documentation",
"Topic :: Documentation :: Sphinx",
"Topic :: Software Development",
"Topic :: Software Development :: Documentation",
"Topic :: Text Processing",
"Topic :: Text Processing :: General",
"Topic :: Utilities",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Programming Language :: Python :: 2",
"Programming Language :: Python :: 2.7",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.4",
"Programming Language :: Python :: 3.5",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Framework :: Sphinx",
],
author="Takayuki SHIMIZUKAWA",
author_email="shimizukawa@gmail.com",
......@@ -59,6 +62,7 @@ setup(
include_package_data=True,
zip_safe=False,
install_requires=install_requires,
python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*",
extras_require=extras_require,
entry_points="""\
[console_scripts]
......
# -*- coding: utf-8 -*-
__version__ = '0.9.12'
__version__ = '1.0.0'
......@@ -22,13 +22,14 @@ def get_lang_dirs(path):
# ==================================
# commands
def update(locale_dir, pot_dir, languages):
def update(locale_dir, pot_dir, languages, line_width=76):
"""
Update specified language's po files from pot.
:param unicode locale_dir: path for locale directory
:param unicode pot_dir: path for pot directory
:param tuple languages: languages to update po files
:param number line_width: maximum line wdith of po files
:return: {'create': 0, 'update': 0, 'notchanged': 0}
:rtype: dict
"""
......@@ -60,14 +61,14 @@ def update(locale_dir, pot_dir, languages):
status['update'] += 1
click.echo('Update: {0} +{1}, -{2}'.format(
po_file, len(added), len(deleted)))
c.dump_po(po_file, cat)
c.dump_po(po_file, cat, line_width)
else:
status['notchanged'] += 1
click.echo('Not Changed: {0}'.format(po_file))
else: # new po file
status['create'] += 1
click.echo('Create: {0}'.format(po_file))
c.dump_po(po_file, cat_pot)
c.dump_po(po_file, cat_pot, line_width)
return status
......
......@@ -23,11 +23,12 @@ def load_po(filename):
return pofile.read_po(f, charset=charset)
def dump_po(filename, catalog):
def dump_po(filename, catalog, line_width=76):
"""write po/pot file from catalog object
:param unicode filename: path to po file
:param catalog: catalog object
:param line_width: maximum line wdith of po files
:return: None
"""
dirname = os.path.dirname(filename)
......@@ -36,7 +37,7 @@ def dump_po(filename, catalog):
# Because babel automatically encode strings, file should be open as binary mode.
with io.open(filename, 'wb') as f:
pofile.write_po(f, catalog)
pofile.write_po(f, catalog, line_width)
def write_mo(filename, catalog):
......
......@@ -4,11 +4,9 @@
~~~~~~~~~~~
Sphinx utility that make it easy to translate and to apply translation.
:copyright: Copyright 2013 by Takayuki SHIMIZUKAWA.
:copyright: Copyright 2019 by Takayuki SHIMIZUKAWA.
:license: BSD, see LICENSE for details.
"""
from __future__ import with_statement
import re
import os
from glob import glob
......@@ -124,6 +122,14 @@ option_language = click.option(
multiple=True,
help="Target language to update po files. Default is ALL.")
option_line_width = click.option(
'-w', '--line-width',
envvar=ENVVAR_PREFIX + '_LINE_WIDTH',
type=int, default=76, metavar='<WIDTH>', show_default=True,
multiple=False,
help='The maximum line width for the po files, 0 or a negative number '
'disable line wrapping')
option_transifex_username = click.option(
'--transifex-username',
envvar=ENVVAR_PREFIX + '_TRANSIFEX_USERNAME',
......@@ -227,7 +233,8 @@ def main(ctx, config, tag):
@option_locale_dir
@option_pot_dir
@option_language
def update(locale_dir, pot_dir, language):
@option_line_width
def update(locale_dir, pot_dir, language, line_width):
"""
Update specified language's po files from pot.
......@@ -253,7 +260,7 @@ def update(locale_dir, pot_dir, language):
% locals())
raise click.BadParameter(msg, param_hint='language')
basic.update(locale_dir, pot_dir, languages)
basic.update(locale_dir, pot_dir, languages, line_width)
@main.command()
......
# -*- coding: utf-8 -*-
if False:
from typing import Iterator, List
# port from https://github.com/sphinx-doc/sphinx/blob/ad41e0b/sphinx/util/tags.py
class Tags(object):
def __init__(self, tags=None):
# type: (List[unicode]) -> None
# type: (List[str]) -> None
self.tags = dict.fromkeys(tags or [], True)
def has(self, tag):
# type: (unicode) -> bool
# type: (str) -> bool
return tag in self.tags
__contains__ = has
def __iter__(self):
# type: () -> Iterator[unicode]
# type: () -> Iterator[str]
return iter(self.tags)
def add(self, tag):
# type: (unicode) -> None
# type: (str) -> None
self.tags[tag] = True
def remove(self, tag):
# type: (unicode) -> None
# type: (str) -> None
self.tags.pop(tag, None)
......@@ -15,9 +15,12 @@ from .catalog import load_po
# To avoid using invalid resource name, append underscore to such names.
# As a limitation, append `_` doesn't care about collision to other resources.
# e.g. 'glossary' and 'glossary_' are pushed as a 'glossary_'.
# e.g. 'glossary' and 'glossary_' are pushed as a 'glossary_'. The following
# resource names are reserved slugs, Transifex will reply with an error on these
# resource names.
IGNORED_RESOURCE_NAMES = (
'glossary', # transifex reject this name
'glossary',
'settings',
)
TRANSIFEXRC_TEMPLATE = """\
......
......@@ -5,7 +5,7 @@
PyTest utilities.
:copyright: Copyright 2015 by Takayuki SHIMIZUKAWA.
:copyright: Copyright 2019 by Takayuki SHIMIZUKAWA.
:license: BSD, see LICENSE for details.
"""
import os
......@@ -14,7 +14,7 @@ import pytest
from path import path
__dir__ = path(os.path.dirname(os.path.abspath(__file__)))
_dir = path(os.path.dirname(os.path.abspath(__file__)))
@pytest.fixture(scope="function")
......@@ -22,7 +22,7 @@ def temp(request, tmpdir):
template_dir = 'root'
tmpdir = path(tmpdir)
(__dir__ / template_dir).copytree(tmpdir / template_dir)
(_dir / template_dir).copytree(tmpdir / template_dir)
cwd = os.getcwd()
temp = tmpdir / template_dir
os.chdir(temp)
......
......@@ -5,7 +5,7 @@
Test functions that implements pot related features.
:copyright: Copyright 2015 by Takayuki SHIMIZUKAWA.
:copyright: Copyright 2019 by Takayuki SHIMIZUKAWA.
:license: BSD, see LICENSE for details.
"""
import mock
......
......@@ -5,7 +5,7 @@
Test functions that implements catalog related features.
:copyright: Copyright 2015 by Takayuki SHIMIZUKAWA.
:copyright: Copyright 2019 by Takayuki SHIMIZUKAWA.
:license: BSD, see LICENSE for details.
"""
from babel.messages import Catalog, Message
......
......@@ -5,11 +5,9 @@
Test pot related commands.
:copyright: Copyright 2015 by Takayuki SHIMIZUKAWA.
:copyright: Copyright 2019 by Takayuki SHIMIZUKAWA.
:license: BSD, see LICENSE for details.
"""
from __future__ import with_statement
from click.testing import CliRunner
from sphinx_intl import commands
......
......@@ -5,7 +5,7 @@
Test transifex related commands.
:copyright: Copyright 2015 by Takayuki SHIMIZUKAWA.
:copyright: Copyright 2019 by Takayuki SHIMIZUKAWA.
:license: BSD, see LICENSE for details.
"""
import re
......
......@@ -5,7 +5,7 @@
Test functions that implements transifex related features.
:copyright: Copyright 2015 by Takayuki SHIMIZUKAWA.
:copyright: Copyright 2019 by Takayuki SHIMIZUKAWA.
:license: BSD, see LICENSE for details.
"""
import re
......@@ -127,6 +127,7 @@ def test_update_txconfig_resources_with_potfile_including_symbols(home_in_temp,
('spam-ham/egg.pot', 'spam-ham--egg_pot'),
('glossary', 'glossary_'),
('glossary_', 'glossary_'),
('settings', 'settings_'),
])
def test_normalize_resource_name(input, expected):
_callSUT = transifex.normalize_resource_name
......
[tox]
envlist=py36,py35,py34,py27,flake8,sdist
envlist=py37,py36,py35,py27,flake8,sdist
[testenv]
deps=-e.[transifex,test]
......