mo-installer 0.3.0
Smoothly integrates mo files in setuptools packaging
License: MIT License
Requires Python: >=3

============
mo_installer
============

Help to install gettext mo file in a setuptools package.

Current status
--------------

This package is fully functional, but should still be considered as beta because it has not been enough tested

Goals
-----

``setuptools`` has currently little support for ``gettext`` mo files generation and packaging. babel_ provides a nice integration, but is a rather large package. This intends to be a small package with examples in order to help developpers to smoothly integrate ``gettext`` internationalization in their packages.

Usage
-----

To have mo file generation at build time, a package developper only has to:

* prepare its po files somewhere in a directory. Under that directory, the po files can be installed:

  * directly in the directory with a name like ``domain-lang.po`` (ex: ``msg-fr_FR.po``)
  * in a ``lang`` sub-directory like ``lang/domain.po`` (ex: ``fr/msg.po``)
  * in a ``LC_MESSAGES`` sub-directory like ``lang/LC_MESSAGES/domain.po`` (ex: ``fr/LC_MESSAGES/msg.po``)

* declare in its ``setup.py`` that he wants to use ``mo_installer``, and where the po files are::

    setup(
        ...
        setup_require = ["mo_installer"],
        locale_src = src_locale_top_level_dir,
    )

and that's all!

The ``mo_installer`` module automatically adds a ``build_mo`` setuptools command that is automatically called from ``build_py``. It builds the mo files and installs them under the main package in a ``locale/lang/LC_MESSAGES`` folder. So, in the above examples, we end with a ``locale/lang/LC_MESSAGES/msg.mo`` file.

Configuration
-------------

The source and destination folders can be configured with ``setup`` parameters:

* ``locale_src`` is the source directory (relative to the source installation, i.e. the directory containing the ``setup.py`` file). By default it is ``locale`` under the main package
* ``locale_dir`` is the top level locale directory (relative to the main package). By default it is ``locale``.

The defaults try to be compatible with babel_ .

Installing
----------

End user installation
*********************

The package can be installed from `PyPI <https://pypi.org/project/mo_installer>`_. But installation is not required when ``pip`` is used: ``setup_require`` automatically finds the package and installs it in the local ``.eggs`` directory

Developper installation
***********************

If you want to contribute or integrate mo_installer in your own code, you should get a copy of the full tree from `GitHUB <https://github.com/s-ball/mo_installer>`_::

  git clone https://github.com/s-ball/mo_installer.git [your_working_copy_folder]

FAQ
---

Q: I have configured my project, but ``python setup.py install`` chokes on ``mo_installer`` not found

A: ``pip`` knows how to fetch setup requirements before building. But when you run directly ``python setup.py install``, there is no place to download them because install has already started. In that case, you must manually install ``mo_installer`` with pip.

----

Q: The mo files generated by ``mo_installer`` seem to not contain a hash table

A: They do not. As ``mo_installer`` is based on ``msgfmt.py`` it cannot generate a hash table and ``gettext`` will use a binary search. BTW, babel_ does not generate any hash table either.

Running the tests
-----------------

As the project intends to be PyPI compatible, you can simply run tests from the main folder with::

  python setup.py test

Some tests depend on pyfakefs_, which is automatically intalled from PyPI when you run `python setup.py test`. But it is not require for using ``mo_installer``, nor installed by ``pip install mo_installer``.

Contributing
------------

As this project is developped on my free time, I cannot guarantee very fast feedbacks. Anyway, I shall be glad to receive issues or pull requests on GitHUB. 

Versioning
----------

This project uses a standard Major.Minor.Patch versioning pattern. Inside a major version, public API stability is expected (at least after 1.0.0 version will be published).

License
-------

This project is licensed under the MIT License - see the LICENSE_ file for details

Acknowledgments
---------------

* The excellent pyfakefs_ allows integration tests to run on a fake file system

.. _babel: http://babel.pocoo.org/
.. _LICENSE: https://github.com/s-ball/mo_installer/blob/master/LICENSE
.. _pyfakefs: http://pyfakefs.org