Merge branch 'working-docker' into 'master'

Working docker

See merge request !4

plugins/i18n_subsites/implementing_language_buttons.rst

------------------------------
-Implementing language buttons
------------------------------
-
-Each article with translations has translations links, but that's the
-only way to switch between language subsites.
-
-For this reason it is convenient to add language buttons to the top
-menu bar to make it simple to switch between the language subsites on
-all pages.
-
-Example designs
----------------
-
-Language buttons showing other available languages
-..................................................
-
-The ``extra_siteurls`` dictionary is a mapping of all other (not the
-``DEFAULT_LANG`` of the current (sub-)site) languages to the
-``SITEURL`` of the respective (sub-)sites
-
-.. code-block:: jinja
-
-   <!-- SNIP -->
-   <nav><ul>
-   {% if extra_siteurls %}
-   {% for lang, url in extra_siteurls.items() %}
-   <li><a href="{{ url }}/">{{ lang }}</a></li>
-   {% endfor %}
-   <!-- separator -->
-   <li style="background-color: white; padding: 5px;">&nbsp</li>
-   {% endif %}
-   {% for title, link in MENUITEMS %}
-   <!-- SNIP -->
-
-Notice the slash ``/`` after ``{{ url }}``, this makes sure it works
-with local development when ``SITEURL == ''``.
-
-Language buttons showing all available languages, current is active
-...................................................................
-
-The ``extra_siteurls`` dictionary is a mapping of all languages to the
-``SITEURL`` of the respective (sub-)sites. This template sets the
-language of the current (sub-)site as active.
-
-.. code-block:: jinja
-
-   <!-- SNIP -->
-   <nav><ul>
-   {% if lang_siteurls %}
-   {% for lang, url in lang_siteurls.items() %}
-   <li{% if lang == DEFAULT_LANG %} class="active"{% endif %}><a href="{{ url }}/">{{ lang }}</a></li>
-   {% endfor %}
-   <!-- separator -->
-   <li style="background-color: white; padding: 5px;">&nbsp</li>
-   {% endif %}
-   {% for title, link in MENUITEMS %}
-   <!-- SNIP -->
-
-
-Tips and tricks
----------------
-
-Showing more than language codes
-................................
-
-If you want the language buttons to show e.g. the names of the
-languages or flags [#flags]_, not just the language codes, you can use
-a jinja filter to translate the language codes
-
-
-.. code-block:: python
-
-   languages_lookup = {
-		'en': 'English',
-		'cz': 'Čeština',
-		}
-
-   def lookup_lang_name(lang_code):
-       return languages_lookup[lang_code]
-
-   JINJA_FILTERS = {
-		...
-		'lookup_lang_name': lookup_lang_name,
-		}
-
-And then the link content becomes
-
-.. code-block:: jinja
-
-   <!-- SNIP -->
-   {% for lang, siteurl in lang_siteurls.items() %}
-   <li{% if lang == DEFAULT_LANG %} class="active"{% endif %}><a href="{{ siteurl }}/">{{ lang | lookup_lang_name }}</a></li>
-   {% endfor %}
-   <!-- SNIP -->
-
-
-Changing the order of language buttons
-......................................
-
-Because ``lang_siteurls`` and ``extra_siteurls`` are instances of
-``OrderedDict`` with ``main_lang`` being always the first key, you can
-change the order through a jinja filter.
-
-.. code-block:: python
-
-   def my_ordered_items(ordered_dict):
-       items = list(ordered_dict.items())
-       # swap first and last using tuple unpacking
-       items[0], items[-1] = items[-1], items[0]
-       return items
-
-   JINJA_FILTERS = {
-		...
-		'my_ordered_items': my_ordered_items,
-		}
-
-And then the ``for`` loop line in the template becomes
-
-.. code-block:: jinja
-
-   <!-- SNIP -->
-   {% for lang, siteurl in lang_siteurls | my_ordered_items %}
-   <!-- SNIP -->
-
-
-.. [#flags] Although it may look nice, `w3 discourages it
-            <http://www.w3.org/TR/i18n-html-tech-lang/#ri20040808.173208643>`_.

plugins/i18n_subsites/localizing_using_jinja2.rst

------------------------------
-Localizing themes with Jinja2
------------------------------
-
-1. Localize templates
----------------------
-
-To enable the |ext| extension in your templates, you must add it to
-``JINJA_EXTENSIONS`` in your Pelican configuration
-
-.. code-block:: python
-
-  JINJA_EXTENSIONS = ['jinja2.ext.i18n', ...]
-
-Then follow the `Jinja2 templating documentation for the I18N plugin
-<http://jinja.pocoo.org/docs/templates/#i18n>`_ to make your templates
-localizable. This usually means surrounding strings with the ``{%
-trans %}`` directive or using ``gettext()`` in expressions
-
-.. code-block:: jinja
-
-    {% trans %}translatable content{% endtrans %}
-    {{ gettext('a translatable string') }}
-
-For pluralization support, etc. consult the documentation.
-
-To enable `newstyle gettext calls
-<http://jinja.pocoo.org/docs/extensions/#newstyle-gettext>`_ the
-``I18N_GETTEXT_NEWSTYLE`` config variable must be set to ``True``
-(default).
-
-.. |ext| replace:: ``jinja2.ext.i18n``
-
-2. Specify translations location
---------------------------------
-
-The |ext| extension uses the `Python gettext library
-<http://docs.python.org/library/gettext.html>`_ for translating
-strings.
-
-In your Pelican config you can give the path in which to look for
-translations in the ``I18N_GETTEXT_LOCALEDIR`` variable. If not given,
-it is assumed to be the ``translations`` subfolder in the top folder
-of the theme specified by ``THEME``.
-
-The domain of the translations (the name of each translation file is
-``domain.mo``) is controlled by the ``I18N_GETTEXT_DOMAIN`` config
-variable (defaults to ``messages``).
-
-Example
-.......
-
-With the following in your Pelican settings file
-
-.. code-block:: python
-
-  I18N_GETTEXT_LOCALEDIR = 'some/path/'
-  I18N_GETTEXT_DOMAIN = 'my_domain'
-
-the translation for language 'cz' will be expected to be in
-``some/path/cz/LC_MESSAGES/my_domain.mo``
-
-
-3. Extract translatable strings and translate them
---------------------------------------------------
-
-There are many ways to extract translatable strings and create
-``gettext`` compatible translations. You can create the ``*.po`` and
-``*.mo`` message catalog files yourself, or you can use some helper
-tool as described in `the Python gettext library tutorial
-<http://docs.python.org/library/gettext.html#internationalizing-your-programs-and-modules>`_.
-
-You of course don't need to provide a translation for the language in
-which the templates are written which is assumed to be the original
-``DEFAULT_LANG``. This can be overridden in the
-``I18N_TEMPLATES_LANG`` variable.
-
-Recommended tool: babel
-.......................
-
-`Babel <http://babel.pocoo.org/>`_ makes it easy to extract
-translatable strings from the localized Jinja2 templates and assists
-with creating translations as documented in this `Jinja2-Babel
-tutorial
-<http://pythonhosted.org/Flask-Babel/#translating-applications>`_
-[#flask]_ on which the following is based.
-
-1. Add babel mapping
-~~~~~~~~~~~~~~~~~~~~
-
-Let's assume that you are localizing a theme in ``themes/my_theme/``
-and that you use the default settings, i.e. the default domain
-``messages`` and will put the translations in the ``translations``
-subdirectory of the theme directory as
-``themes/my_theme/translations/``.
-
-It is up to you where to store babel mappings and translation files
-templates (``*.pot``), but a convenient place is to put them in
-``themes/my_theme/`` and work in that directory. From now on let's
-assume that it will be our current working directory (CWD).
-
-To tell babel to extract translatable strings from the templates
-create a mapping file ``babel.cfg`` with the following line
-
-.. code-block:: cfg
-
-    [jinja2: templates/**.html]
-
-
-2. Extract translatable strings from templates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Run the following command to create a ``messages.pot`` message catalog
-template file from extracted translatable strings
-
-.. code-block:: bash
-
-    pybabel extract --mapping babel.cfg --output messages.pot ./
-
-
-3. Initialize message catalogs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you want to translate the template to language ``lang``, run the
-following command to create a message catalog
-``translations/lang/LC_MESSAGES/messages.po`` using the template
-``messages.pot``
-
-.. code-block:: bash
-
-    pybabel init --input-file messages.pot --output-dir translations/ --locale lang --domain messages
-
-babel expects ``lang`` to be a valid locale identifier, so if e.g. you
-are translating for language ``cz`` but the corresponding locale is
-``cs``, you have to use the locale identifier. Nevertheless, the
-gettext infrastructure should later correctly find the locale for a
-given language.
-
-4. Fill the message catalogs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The message catalog files format is quite intuitive, it is fully
-documented in the `GNU gettext manual
-<http://www.gnu.org/software/gettext/manual/gettext.html#PO-Files>`_. Essentially,
-you fill in the ``msgstr`` strings
-
-
-.. code-block:: po
-
-    msgid "just a simple string"
-    msgstr "jenom jednoduchý řetězec"
-
-    msgid ""
-    "some multiline string"
-    "looks like this"
-    msgstr ""
-    "nějaký více řádkový řetězec"
-    "vypadá takto"
-
-You might also want to remove ``#,fuzzy`` flags once the translation
-is complete and reviewed to show that it can be compiled.
-
-5. Compile the message catalogs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The message catalogs must be compiled into binary format using this
-command
-
-.. code-block:: bash
-
-    pybabel compile --directory translations/ --domain messages
-
-This command might complain about "fuzzy" translations, which means
-you should review the translations and once done, remove the fuzzy
-flag line.
-
-(6.) Update the catalogs when templates change
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you add any translatable patterns into your templates, you have to
-update your message catalogs too.  First you extract a new message
-catalog template as described in the 2. step. Then you run the
-following command [#pybabel_error]_
-
-.. code-block:: bash
-
-   pybabel update --input-file messages.pot --output-dir translations/ --domain messages
-
-This will merge the new patterns with the old ones. Once you review
-and fill them, you have to recompile them as described in the 5. step.
-
-.. [#flask] Although the tutorial is focused on Flask-based web
-            applications, the linked translation tutorial is not
-            Flask-specific.
-.. [#pybabel_error] If you get an error ``TypeError: must be str, not
-                    bytes`` with Python 3.3, it is likely you are
-                    suffering from this `bug
-                    <https://github.com/mitsuhiko/flask-babel/issues/43>`_.
-                    Until the fix is released, you can use babel with
-                    Python 2.7.

plugins/i18n_subsites/test_data/content/pages/hidden-page-cz.rst

-404 stránka
-===========
-:slug: 404
-:lang: cz
-:status: hidden
-
-Jednoduchá 404 stránka.

plugins/i18n_subsites/test_data/content/pages/hidden-page-de.rst

-Eine 404 Seite
-==============
-:slug: 404
-:lang: de
-:status: hidden
-
-Eine einfache 404 Seite.

plugins/i18n_subsites/test_data/content/pages/hidden-page-en.rst

-A 404 page
-==========
-:slug: 404
-:lang: en
-:status: hidden
-
-A simple 404 page.

plugins/i18n_subsites/test_data/content/pages/untranslated-page.rst

-Untranslated page
-=================
-:lang: en
-
-This page has no translation.

plugins/i18n_subsites/test_data/content/translated_article-cz.rst

-Přeložený článek
-================
-:slug: translated-article
-:lang: cz
-:date: 2014-09-15
-
-Jednoduchý článek s překlady.
-Zde je odkaz na `nějaký obrázek <{filename}/images/img.png>`_.

plugins/i18n_subsites/test_data/content/translated_article-de.rst

-Ein übersetzter Artikel
-=======================
-:slug: translated-article
-:lang: de
-:date: 2014-09-14
-
-Ein einfacher Artikel mit einer Übersetzung.
-Hier ist ein Link zur `einigem Bild <{filename}/images/img.png>`_.

plugins/i18n_subsites/test_data/content/translated_article-en.rst

-A translated article
-====================
-:slug: translated-article
-:lang: en
-:date: 2014-09-13
-
-A simple article with a translation.
-Here is a link to `some image <{filename}/images/img.png>`_.

plugins/i18n_subsites/test_data/content/untranslated_article-en.rst

-An untranslated article
-=======================
-:date: 2014-07-14
-:lang: en
-
-An article without a translation.
-Here is a link to an `untranslated page`_
-
-.. _`untranslated page`: {filename}/pages/untranslated-page.rst

plugins/i18n_subsites/test_data/localized_theme/babel.cfg

-[jinja2: templates/**.html]
-

plugins/i18n_subsites/test_data/localized_theme/messages.pot

-# Translations template for PROJECT.
-# Copyright (C) 2014 ORGANIZATION
-# This file is distributed under the same license as the PROJECT project.
-# FIRST AUTHOR <EMAIL@ADDRESS>, 2014.
-#
-#, fuzzy
-msgid ""
-msgstr ""
-"Project-Id-Version: PROJECT VERSION\n"
-"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2014-07-13 12:25+0200\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <LL@li.org>\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=utf-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-"Generated-By: Babel 1.3\n"
-
-#: templates/base.html:3
-msgid "Welcome to our"
-msgstr ""
-

plugins/i18n_subsites/test_data/localized_theme/templates/base.html

-{% extends "!simple/base.html" %}
-
-{% block title %}{% trans %}Welcome to our{% endtrans %} {{ SITENAME }}{% endblock %}
-{% block head %}
-{{ super() }}
-<link rel="stylesheet" href="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/style.css" />
-{% endblock %}

plugins/i18n_subsites/test_data/localized_theme/translations/de/LC_MESSAGES/messages.po

-# German translations for PROJECT.
-# Copyright (C) 2014 ORGANIZATION
-# This file is distributed under the same license as the PROJECT project.
-# FIRST AUTHOR <EMAIL@ADDRESS>, 2014.
-#
-msgid ""
-msgstr ""
-"Project-Id-Version: PROJECT VERSION\n"
-"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2014-07-13 12:25+0200\n"
-"PO-Revision-Date: 2014-07-13 12:26+0200\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: de <LL@li.org>\n"
-"Plural-Forms: nplurals=2; plural=(n != 1)\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=utf-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-"Generated-By: Babel 1.3\n"
-
-#: templates/base.html:3
-msgid "Welcome to our"
-msgstr "Willkommen Sie zur unserer"
-

plugins/i18n_subsites/test_data/output/an-untranslated-article.html

-<!DOCTYPE html>
-<html lang="en">
-<head>
-          <title>Welcome to our Testing site</title>
-        <meta charset="utf-8" />
-        <link href="http://example.com/test/feeds_all.atom.xml" type="application/atom+xml" rel="alternate" title="Testing site Full Atom Feed" />
-
-<link rel="stylesheet" href="http://example.com/test/theme/style.css" />
-
-
-
-</head>
-
-<body id="index" class="home">
-        <header id="banner" class="body">
-                <h1><a href="http://example.com/test/">Testing site <strong></strong></a></h1>
-        </header><!-- /#banner -->
-        <nav id="menu"><ul>
-            <li><a href="http://example.com/test/pages/untranslated-page.html">Untranslated page</a></li>
-        </ul></nav><!-- /#menu -->
-<section id="content" class="body">
-  <header>
-    <h2 class="entry-title">
-      <a href="http://example.com/test/an-untranslated-article.html" rel="bookmark"
-         title="Permalink to An untranslated article">An untranslated article</a></h2>
- 
-  </header>
-  <footer class="post-info">
-    <time class="published" datetime="2014-07-14T00:00:00+00:00">
-      Mon 14 July 2014
-    </time>
-    <address class="vcard author">
-      By           <a class="url fn" href="http://example.com/test/author/the-tester.html">The Tester</a>
-    </address>
-  </footer><!-- /.post-info -->
-  <div class="entry-content">
-    <p>An article without a translation.
-Here is a link to an <a class="reference external" href="http://example.com/test/pages/untranslated-page.html">untranslated page</a></p>
-
-  </div><!-- /.entry-content -->
-</section>
-        <footer id="contentinfo" class="body">
-                <address id="about" class="vcard body">
-                Proudly powered by <a href="http://getpelican.com/">Pelican</a>,
-                which takes great advantage of <a href="http://python.org">Python</a>.
-                </address><!-- /#about -->
-        </footer><!-- /#contentinfo -->
-</body>
-</html>
\ No newline at end of file

plugins/i18n_subsites/test_data/output/cz/an-untranslated-article-en.html

-<!DOCTYPE html>
-<html lang="cz">
-<head>
-          <title>Welcome to our Testovací stránka</title>
-        <meta charset="utf-8" />
-        <link href="http://example.com/test/feeds_all.atom.xml" type="application/atom+xml" rel="alternate" title="Testovací stránka Full Atom Feed" />
-
-<link rel="stylesheet" href="http://example.com/test/cz/../theme/style.css" />
-
-
-
-</head>
-
-<body id="index" class="home">
-        <header id="banner" class="body">
-                <h1><a href="http://example.com/test/cz/">Testovací stránka <strong></strong></a></h1>
-        </header><!-- /#banner -->
-        <nav id="menu"><ul>
-        </ul></nav><!-- /#menu -->
-<section id="content" class="body">
-  <header>
-    <h2 class="entry-title">
-      <a href="http://example.com/test/cz/an-untranslated-article-en.html" rel="bookmark"
-         title="Permalink to An untranslated article">An untranslated article</a></h2>
- 
-  </header>
-  <footer class="post-info">
-    <time class="published" datetime="2014-07-14T00:00:00+00:00">
-      Mon 14 July 2014
-    </time>
-    <address class="vcard author">
-      By           <a class="url fn" href="http://example.com/test/cz/author/test-testovic.html">Test Testovič</a>
-    </address>
-  </footer><!-- /.post-info -->
-  <div class="entry-content">
-    <p>An article without a translation.
-Here is a link to an <a class="reference external" href="http://example.com/test/cz/../pages/untranslated-page.html">untranslated page</a></p>
-
-  </div><!-- /.entry-content -->
-</section>
-        <footer id="contentinfo" class="body">
-                <address id="about" class="vcard body">
-                Proudly powered by <a href="http://getpelican.com/">Pelican</a>,
-                which takes great advantage of <a href="http://python.org">Python</a>.
-                </address><!-- /#about -->
-        </footer><!-- /#contentinfo -->
-</body>
-</html>
\ No newline at end of file