From e4dc7443ddf8e5e3d861c66e0cef565a6d907789 Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 20:07:59 +0200 Subject: Update documentation for Lingua 2 --- docs/narr/i18n.rst | 182 ++++++++++++++--------------------------------------- 1 file changed, 48 insertions(+), 134 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 5f50ca212..31b63664b 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -245,88 +245,69 @@ GNU gettext uses three types of files in the translation framework, A ``.po`` file is turned into a machine-readable binary file, which is the ``.mo`` file. Compiling the translations to machine code - makes the localized program run faster. + makes the localized program start faster. The tools for working with :term:`gettext` translation files related to a -:app:`Pyramid` application is :term:`Babel` and :term:`Lingua`. Lingua is a -Babel extension that provides support for scraping i18n references out of -Python and Chameleon files. +:app:`Pyramid` application are :term:`Lingua` and :term:`Gettext`. Lingua +can scrape i18n references out of Python and Chameleon files and create +the ``.pot`` file. Gettext includes tools to update a ``.po`` file from +an updated ``.pot`` file and to compile ``.po`` files to ``.mo`` files. .. index:: - single: Babel + single: Gettext single: Lingua .. _installing_babel: -Installing Babel and Lingua -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Installing Lingua and Gettext +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order for the commands related to working with ``gettext`` translation -files to work properly, you will need to have :term:`Babel` and -:term:`Lingua` installed into the same environment in which :app:`Pyramid` is +files to work properly, you will need to have :term:`Lingua` and +:term:`Gettext` installed into the same environment in which :app:`Pyramid` is installed. Installation on UNIX ++++++++++++++++++++ -If the :term:`virtualenv` into which you've installed your :app:`Pyramid` -application lives in ``/my/virtualenv``, you can install Babel and Lingua -like so: +Gettext is often already installed on UNIX systems. You can check if it is +installed by testing if the ``msgfmt`` command is available. If it is not +available you can install it through the packaging system from your OS; +the package name is almost always ``gettext``. For example on a Debian or +Ubuntu system run this command: .. code-block:: text - $ cd /my/virtualenv - $ $VENV/bin/easy_install Babel lingua + $ sudo apt-get install gettext -Installation on Windows -+++++++++++++++++++++++ - -If the :term:`virtualenv` into which you've installed your :app:`Pyramid` -application lives in ``C:\my\virtualenv``, you can install Babel and Lingua +Installing Lingua is done with the Python packaging tools. If the +:term:`virtualenv` into which you've installed your :app:`Pyramid` application +lives in ``/my/virtualenv``, you can install Lingua like so: .. code-block:: text - C> %VENV%\Scripts\easy_install Babel lingua + $ cd /my/virtualenv + $ $VENV/bin/pip install lingua -.. index:: - single: Babel; message extractors - single: Lingua +Installation on Windows ++++++++++++++++++++++++ -Changing the ``setup.py`` -+++++++++++++++++++++++++ +There are several ways to install Gettext on Windows: it is included in the +`Cygwin `_ collection, or you can use the `installer +from the GnuWin32 `_ +or compile it yourself. Make sure the installation path is added to your +``$PATH``. -You need to add a few boilerplate lines to your application's ``setup.py`` -file in order to properly generate :term:`gettext` files from your -application. -.. note:: See :ref:`project_narr` to learn about the - composition of an application's ``setup.py`` file. +Installing Lingua is done with the Python packaging tools. If the +:term:`virtualenv` into which you've installed your :app:`Pyramid` application +lives in ``C:\my\virtualenv``, you can install Lingua like so: -In particular, add the ``Babel`` and ``lingua`` distributions to the -``install_requires`` list and insert a set of references to :term:`Babel` -*message extractors* within the call to :func:`setuptools.setup` inside your -application's ``setup.py`` file: +.. code-block:: text -.. code-block:: python - :linenos: + C> %VENV%\Scripts\pip install lingua - setup(name="mypackage", - # ... - install_requires = [ - # ... - 'Babel', - 'lingua', - ], - message_extractors = { '.': [ - ('**.py', 'lingua_python', None ), - ('**.pt', 'lingua_xml', None ), - ]}, - ) - -The ``message_extractors`` stanza placed into the ``setup.py`` file causes -the :term:`Babel` message catalog extraction machinery to also consider -``*.pt`` files when doing message id extraction. .. index:: pair: extracting; messages @@ -336,90 +317,20 @@ the :term:`Babel` message catalog extraction machinery to also consider Extracting Messages from Code and Templates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once Babel and Lingua are installed and your application's ``setup.py`` file -has the correct message extractor references, you may extract a message -catalog template from the code and :term:`Chameleon` templates which reside -in your :app:`Pyramid` application. You run a ``setup.py`` command to -extract the messages: +Once Lingua is installed you may extract a message catalog template from the +code and :term:`Chameleon` templates which reside in your :app:`Pyramid` +application. You run a ``pot-create`` command to extract the messages: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $VENV/bin/python setup.py extract_messages + $ $VENT/bin/pot-create src > myapplication/locale/myapplication.pot The message catalog ``.pot`` template will end up in: ``myapplication/locale/myapplication.pot``. -.. index:: - single: translation domains - -Translation Domains -+++++++++++++++++++ - -The name ``myapplication`` above in the filename ``myapplication.pot`` -denotes the :term:`translation domain` of the translations that must -be performed to localize your application. By default, the -translation domain is the :term:`project` name of your -:app:`Pyramid` application. - -To change the translation domain of the extracted messages in your project, -edit the ``setup.cfg`` file of your application, The default ``setup.cfg`` -file of a ``pcreate`` -generated :app:`Pyramid` application has stanzas in it -that look something like the following: - -.. code-block:: ini - :linenos: - - [compile_catalog] - directory = myproject/locale - domain = MyProject - statistics = true - - [extract_messages] - add_comments = TRANSLATORS: - output_file = myproject/locale/MyProject.pot - width = 80 - - [init_catalog] - domain = MyProject - input_file = myproject/locale/MyProject.pot - output_dir = myproject/locale - - [update_catalog] - domain = MyProject - input_file = myproject/locale/MyProject.pot - output_dir = myproject/locale - previous = true - -In the above example, the project name is ``MyProject``. To indicate -that you'd like the domain of your translations to be ``mydomain`` -instead, change the ``setup.cfg`` file stanzas to look like so: - -.. code-block:: ini - :linenos: - - [compile_catalog] - directory = myproject/locale - domain = mydomain - statistics = true - - [extract_messages] - add_comments = TRANSLATORS: - output_file = myproject/locale/mydomain.pot - width = 80 - - [init_catalog] - domain = mydomain - input_file = myproject/locale/mydomain.pot - output_dir = myproject/locale - - [update_catalog] - domain = mydomain - input_file = myproject/locale/mydomain.pot - output_dir = myproject/locale - previous = true .. index:: pair: initializing; message catalog @@ -432,15 +343,17 @@ Once you've extracted messages into a ``.pot`` file (see in the ``.pot`` file, you need to generate at least one ``.po`` file. A ``.po`` file represents translations of a particular set of messages to a particular locale. Initialize a ``.po`` file for a specific -locale from a pre-generated ``.pot`` template by using the ``setup.py -init_catalog`` command: +locale from a pre-generated ``.pot`` template by using the ``msginit`` +command: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $VENV/bin/python setup.py init_catalog -l es + $ cd myapplication/locale + $ mkdir -p es/LC_MESSAGES + $ msginit -l es es/LC_MESSAGES/myapplication.po -By default, the message catalog ``.po`` file will end up in: +This will create a new the message catalog ``.po`` file will in: ``myapplication/locale/es/LC_MESSAGES/myapplication.po``. @@ -465,12 +378,13 @@ files based on changes to the ``.pot`` file, so that the new and changed messages can also be translated or re-translated. First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. -Then use the ``setup.py update_catalog`` command. +Then use the ``msgmerge`` command. .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $VENV/bin/python setup.py update_catalog + $ cd myapplication/locale + $ msgmerge --update es/LC_MESSAGES/myapplication.po myapplication.pot .. index:: pair: compiling; message catalog @@ -481,12 +395,12 @@ Compiling a Message Catalog File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Finally, to prepare an application for performing actual runtime -translations, compile ``.po`` files to ``.mo`` files: +translations, compile ``.po`` files to ``.mo`` files use the ``msgfmt``: .. code-block:: text $ cd /place/where/myapplication/setup.py/lives - $ $VENV/bin/python setup.py compile_catalog + $ msgfmt myapplication/locale/*/LC_MESSAGES/*.po This will create a ``.mo`` file for each ``.po`` file in your application. As long as the :term:`translation directory` in which -- cgit v1.2.3 From cfaec8b63b271e141789244ad276d3045e00a2a8 Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:01:43 +0200 Subject: Keep using easy_install. --- docs/narr/i18n.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 31b63664b..122f33130 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -288,7 +288,7 @@ like so: .. code-block:: text $ cd /my/virtualenv - $ $VENV/bin/pip install lingua + $ $VENV/bin/easy_install lingua Installation on Windows +++++++++++++++++++++++ @@ -306,7 +306,7 @@ lives in ``C:\my\virtualenv``, you can install Lingua like so: .. code-block:: text - C> %VENV%\Scripts\pip install lingua + C> %VENV%\Scripts\easy_install lingua .. index:: -- cgit v1.2.3 From d3a70e5e656eea3f527b56e9f03b6f754731dc4a Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:04:57 +0200 Subject: Fix $VENT typo --- docs/narr/i18n.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 122f33130..50e5a6817 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -325,7 +325,7 @@ application. You run a ``pot-create`` command to extract the messages: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale - $ $VENT/bin/pot-create src > myapplication/locale/myapplication.pot + $ $VENV/bin/pot-create src > myapplication/locale/myapplication.pot The message catalog ``.pot`` template will end up in: -- cgit v1.2.3 From c1cbf085fbf4e0280481acfbf1e9b6b0f8692cbd Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:07:24 +0200 Subject: Remove lingua references from setup.cfg description. --- docs/narr/project.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 62b91de0e..3631a9782 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -760,8 +760,8 @@ Our generated ``setup.cfg`` looks like this: :language: guess :linenos: -The values in the default setup file allow various commonly-used -internationalization commands and testing commands to work more smoothly. +The values in the default setup file make the testing commands to work more +smoothly. .. index:: single: package -- cgit v1.2.3 From 0a4433df3711755170396090d8daa69bfaef76f9 Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:09:34 +0200 Subject: Always mention the msg* commands come from Gettext --- docs/narr/i18n.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 50e5a6817..1de2c8941 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -250,8 +250,9 @@ GNU gettext uses three types of files in the translation framework, The tools for working with :term:`gettext` translation files related to a :app:`Pyramid` application are :term:`Lingua` and :term:`Gettext`. Lingua can scrape i18n references out of Python and Chameleon files and create -the ``.pot`` file. Gettext includes tools to update a ``.po`` file from -an updated ``.pot`` file and to compile ``.po`` files to ``.mo`` files. +the ``.pot`` file. Gettext includes ``msgmerge`` tool to update a ``.po`` file +from an updated ``.pot`` file and ``msgfmt`` to compile ``.po`` files to +``.mo`` files. .. index:: single: Gettext @@ -344,7 +345,7 @@ in the ``.pot`` file, you need to generate at least one ``.po`` file. A ``.po`` file represents translations of a particular set of messages to a particular locale. Initialize a ``.po`` file for a specific locale from a pre-generated ``.pot`` template by using the ``msginit`` -command: +command from Gettext: .. code-block:: text @@ -378,7 +379,7 @@ files based on changes to the ``.pot`` file, so that the new and changed messages can also be translated or re-translated. First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. -Then use the ``msgmerge`` command. +Then use the ``msgmerge`` command from Gettext. .. code-block:: text @@ -395,7 +396,8 @@ Compiling a Message Catalog File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Finally, to prepare an application for performing actual runtime -translations, compile ``.po`` files to ``.mo`` files use the ``msgfmt``: +translations, compile ``.po`` files to ``.mo`` files use the ``msgfmt`` +command from Gettext: .. code-block:: text -- cgit v1.2.3 From 832c2e8967fa1904fb1a0d3e5d707a11c32aa543 Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 21:49:44 +0200 Subject: Remove Babel from all setup.cfg files --- docs/narr/MyProject/setup.cfg | 21 --------------------- 1 file changed, 21 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/MyProject/setup.cfg b/docs/narr/MyProject/setup.cfg index 332e80a60..229a686f8 100644 --- a/docs/narr/MyProject/setup.cfg +++ b/docs/narr/MyProject/setup.cfg @@ -4,24 +4,3 @@ nocapture = 1 cover-package = myproject with-coverage = 1 cover-erase = 1 - -[compile_catalog] -directory = myproject/locale -domain = MyProject -statistics = true - -[extract_messages] -add_comments = TRANSLATORS: -output_file = myproject/locale/MyProject.pot -width = 80 - -[init_catalog] -domain = MyProject -input_file = myproject/locale/MyProject.pot -output_dir = myproject/locale - -[update_catalog] -domain = MyProject -input_file = myproject/locale/MyProject.pot -output_dir = myproject/locale -previous = true -- cgit v1.2.3 From eab0eb5068754da33123d5a7bc3faf025a3fc14e Mon Sep 17 00:00:00 2001 From: Wichert Akkerman Date: Tue, 8 Apr 2014 22:04:47 +0200 Subject: Drop setup.cfg from scaffolds Since setup.cfg is no longer needed for Babel, and no scaffold or documentation references nose there is no need to keep them. --- docs/narr/MyProject/setup.cfg | 6 ------ docs/narr/project.rst | 22 ---------------------- 2 files changed, 28 deletions(-) delete mode 100644 docs/narr/MyProject/setup.cfg (limited to 'docs/narr') diff --git a/docs/narr/MyProject/setup.cfg b/docs/narr/MyProject/setup.cfg deleted file mode 100644 index 229a686f8..000000000 --- a/docs/narr/MyProject/setup.cfg +++ /dev/null @@ -1,6 +0,0 @@ -[nosetests] -match = ^test -nocapture = 1 -cover-package = myproject -with-coverage = 1 -cover-erase = 1 diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 3631a9782..39e55706f 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -492,7 +492,6 @@ structure: │   ├── tests.py │   └── views.py ├── production.ini - ├── setup.cfg └── setup.py The ``MyProject`` :term:`Project` @@ -515,9 +514,6 @@ describe, run, and test your application. #. ``production.ini`` is a :term:`PasteDeploy` configuration file that can be used to execute your application in a production configuration. -#. ``setup.cfg`` is a :term:`setuptools` configuration file used by - ``setup.py``. - #. ``MANIFEST.in`` is a :term:`distutils` "manifest" file, naming which files should be included in a source distribution of the package when ``python setup.py sdist`` is run. @@ -745,24 +741,6 @@ This will create a tarball of your application in a ``dist`` subdirectory named ``MyProject-0.1.tar.gz``. You can send this tarball to other people who want to install and use your application. -.. index:: - single: setup.cfg - -``setup.cfg`` -~~~~~~~~~~~~~ - -The ``setup.cfg`` file is a :term:`setuptools` configuration file. It -contains various settings related to testing and internationalization: - -Our generated ``setup.cfg`` looks like this: - -.. literalinclude:: MyProject/setup.cfg - :language: guess - :linenos: - -The values in the default setup file make the testing commands to work more -smoothly. - .. index:: single: package -- cgit v1.2.3 From c3ef4170b195f08f9563256a3cbdd614d786acef Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 8 Apr 2014 17:51:30 -0400 Subject: make pdf build again --- docs/narr/project.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 39e55706f..0ada1a379 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -476,23 +476,23 @@ structure: .. code-block:: text MyProject/ - ├── CHANGES.txt - ├── MANIFEST.in - ├── README.txt - ├── development.ini - ├── myproject - │   ├── __init__.py - │   ├── static - │   │   ├── pyramid-16x16.png - │   │   ├── pyramid.png - │   │   ├── theme.css - │   │   └── theme.min.css - │   ├── templates - │   │   └── mytemplate.pt - │   ├── tests.py - │   └── views.py - ├── production.ini - └── setup.py + |-- CHANGES.txt + |-- development.ini + |-- MANIFEST.in + |-- myproject + | |-- __init__.py + | |-- static + | | |-- pyramid-16x16.png + | | |-- pyramid.png + | | |-- theme.css + | | `-- theme.min.css + | |-- templates + | | `-- mytemplate.pt + | |-- tests.py + | `-- views.py + |-- production.ini + |-- README.txt + `-- setup.py The ``MyProject`` :term:`Project` --------------------------------- -- cgit v1.2.3