TRANSLATION_README

============
Installation
============

To install all required packages run:

    $ pip install -r djbook/deps.txt

============
How to start
============

You can find .po files in `locale/ru/LC_MESSAGES` folder.

To build documentation HTML run:

    $ ./translator.py create

Generated HTML you can find in `_build/html`.

So find .po you wish to translate, add changes and run `./translator.py create`.

=============
translator.py
=============

----------
Base usage
----------

To list all command run:

    $ ./translator.py --help

To get info about some command run:

    $ ./translator.py help [command_name]

--------------
Output control
--------------

Use ``--debug`` option to see debug info and error traceback.
Use ``-v`` for verbose output.
Use ``-q`` for quiet execute.

---------------
Add new command
---------------

We use https://github.com/dhellmann/cliff with a little bit fixed command loader.
You can find command in ``djbook.commands`` package.

There are three level of output:

    self.app.stdout.write('hi!\n')     # default output
    self.log.info('sending greeting')  # verbose output
    self.log.debug('debugging')        # debug output

====================================================
Update documentation from Django source code
====================================================

Visit https://github.com/django/django, find required tag. Run:

    $ ./translator.py update <tag>

Also there is a little hack to translate hard-coded text.
Add `from sphinx.locale import l_` to `_ext/djangodocs.py` and wrap `version_text` with `l_`.
You may need update localization, see description under.

========================
Translate hardcoded text
========================

Create _ext/locale/django.pot:

    pybabel extract -k _ -k l_ -k lazy_gettext -o djbook/sphinx.pot  _ext/

Update locale catalog:

    pybabel update -i djbook/sphinx.pot -d locale/ -l ru -D sphinx

Create locale catalog(already created):

    pybabel init -i djbook/sphinx.pot -d locale/ -l ru -D sphinx

=====
Notes
=====

In `djbook/_theme/djbook/layout.html` are hardcoded link to comments scripts from server.
Do not forget have them up to date.

=====
Hints
=====

В оригинале часто используют ссылки следующего вида:

    `define and send your own custom signals`_

Sphinx при переводе сначала подставляет перевод, потом рендерит html, по этому
просто перевести текст нельзя т.к. метки с таким названием не будет. Для этого
используем http://sphinx-doc.org/markup/inline.html#ref-role найдя в исходниках
страницы название метки. Например:

    :ref:`определять и посылать свои собственные сигналы <defining-and-sending-signals>`