French translation of user documentation

- also changed doc theme and added favicon
- also updated doc with new generic page components and 'hide menu' setting
- also added translation instructions in contributing.rst

CONTRIBUTING.rst

@@ -76,5 +76,126 @@ If you make a merge request for a feature that impacts ColdCMS usage, you are ad
 The documentation for ColdCMS is generated with Sphinx and ReadtheDocs. To update it :
 
 1. Update the files or add a new file in /docs/usage. The documentation files are in .rst format, see `how to use reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_.
-2. If you want to test the rendered doc locally, run ```make html``` in /doc, and check the output by opening /doc/_build/html/index.html in a web browser.
-3. Once you are happy with it, include the documentation in your merge request.
\ No newline at end of file
+2. If you want to test the rendered doc locally, run ``make html`` in /doc, and check the output by opening /doc/_build/html/index.html in a web browser.
+3. Once you are happy with it, include the documentation in your merge request.
+
+
+7. Translation
+==============
+
+Steps to translate ColdCMS components
+-------------------------------------
+
+    1. Make sure to mark as translatable the strings meant to be displayed to the user. Usually, for that, we import gettext as follows
+
+    .. code-block:: python
+
+        from django.utils.translation import ugettext_lazy as _
+
+    and we mark the translatable strings like this:
+
+    .. code-block:: python
+
+        _("UI String to be translated")
+
+    2. To update the ``django.po`` file containing all the strings to translate, run from the project root (same level as ``manage.py``):
+
+    .. code-block:: shell
+
+        python manage.py makemessages -a
+
+    3. Write the needed translations in ``coldcms/locale/$LANG/LC_MESSAGES/django.po``, where ``$LANG`` is the language (for example ``fr`` for French).
+
+    4. Compile your translations with:
+
+    .. code-block:: shell
+
+        python manage.py compilemessages
+
+
+Steps to translate documentation
+--------------------------------
+
+    1. Install Sphinx internationalization tool 
+
+    .. code-block:: shell
+    
+        pip install sphinx-intl
+
+    2. To update the documentation to be translated, run in ``docs/``
+
+    .. code-block:: shell
+    
+        sphinx-intl update -p _build/gettext -l <lang>
+
+    where ``<lang>`` is the language code, for example ``fr``.
+
+    3. Write the translations in ``.po`` files, in ``docs/locale/$LANG/LC_MESSAGES``, where ``$LANG`` is the language (for example ``fr``).
+
+    4. Build the translated documentation
+
+    .. code-block:: shell
+    
+        sphinx-build -b html -D language=<lang> . _build/html/<lang>
+
+    where ``<lang>`` is the language code, for example ``fr``.
+    Instead, you can also run in the project root:
+
+    .. code-block:: shell
+
+        python manage.py compilemessages
+
+
+**To replace an image in translation (e.g. a screenshot of UI in another language)**
+
+If you want to replace the image ``docs/_static/images/image_name.png`` by another one in the translated version of the documentation, just save your image as ``docs/_static/images/<lang>/image_name_<lang>.png``.
+For example, ``docs/_static/images/blog_index_edit.png`` is replaced in the French translation by ``docs/_static/images/fr/blog_index_edit_fr.png``.
+
+In ``.po`` files, images are included as translatable content. If the image has an alternative text, please translate it in your language (useful for screen readers). Leave the image path as it is, just replace the :alt: text.
+For example, in ``docs/locale/fr/LC_MESSAGES/usage/links.po``:
+
+.. code-block:: python
+
+    msgid ""
+    ".. image:: usage/../_static/images/links.png\n"
+    "   :alt: the link appears in the menu bar"
+    msgstr ""
+    ".. image:: usage/../_static/images/links.png\n"
+    "   :alt: le lien apparaît dans la barre de menu"
+
+
+If the image doesn't have an alternative text, just leave the translation blank:
+
+.. code-block:: python
+
+    msgid ".. image:: usage/../_static/images/links.png\n"
+    msgstr ""
+
+
+**To translate UI elements of the documentation**
+
+**Skip steps 1 to 3** if your language already exists in ``docs/locale/``.
+
+    1. Install Babel:
+
+    .. code-block:: shell
+
+        pip install Babel
+
+    2. To generate ``sphinx-rtd-theme.pot``, run at the project root:
+    
+    .. code-block:: shell
+        
+        python setup.py extract_messages 
+
+    3. Create the ``.po`` file for your language using ``msgmerge`` tool, and place it in your project as ``locale/$LANG/LC_MESSAGES/sphinx.po`` (with ``$LANG`` the language code).
+
+    4. Add translations manually in ``docs/locale/$LANG/LC_MESSAGES/sphinx.po``.
+
+    3. Apply translations
+
+    .. code-block:: python
+    
+        python manage.py compilemessages
+    
+See `this github issue <https://github.com/readthedocs/sphinx_rtd_theme/issues/403#issuecomment-289096940>`_ for further details on translating UI elements of documentation using sphinx-rtd-theme.
\ No newline at end of file

README.rst

@@ -16,7 +16,10 @@ A fully functional CMS optimized for low consumption.
 
 See `here <https://coldcms.hashbang.fr>`_ for blog posts about this.
 
-`User documentation <https://coldcms.readthedocs.io/en/latest/>`_.
+User documentation:
+
+    - `English documentation <https://coldcms.readthedocs.io/en/latest/>`_
+    - `Documentation en français <https://coldcms.readthedocs.io/fr/latest/>`_
 
 
 Description

coldcms/blocks/blocks.py

@@ -28,7 +28,7 @@ class CTABlock(blocks.StructBlock):
         required=False,
         max_length=40,
     )
-    custom_url = blocks.CharBlock(label="External URL", required=False)
+    custom_url = blocks.CharBlock(label=_("External URL"), required=False)
     page = blocks.PageChooserBlock(
         label=_("Link to an internal page"),
         help_text=_("Ignored if the external URL is used"),

coldcms/blog/models.py

@@ -45,7 +45,7 @@ class BlogPage(ColdCMSPageMixin, Page):
         ),
         FieldPanel("intro"),
         FieldPanel("body"),
-        InlinePanel("gallery_images", label="Gallery images"),
+        InlinePanel("gallery_images", label=_("Gallery images")),
     ]
     edit_handler = TabbedInterface([ObjectList(content_panels, heading=_("Content"))])
 

coldcms/locale/fr/LC_MESSAGES/django.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2020-04-27 08:45+0000\n"
+"POT-Creation-Date: 2020-06-02 14:51+0000\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"
@@ -29,6 +29,10 @@ msgstr ""
 "Ce champ est utilisé en tant que texte d'une URL externe ou pour surcharger "
 "le titre d'une Page"
 
+#: coldcms/blocks/blocks.py:31
+msgid "External URL"
+msgstr "Lien externe"
+
 #: coldcms/blocks/blocks.py:33
 msgid "Link to an internal page"
 msgstr "Lien vers une page interne du site"
@@ -57,7 +61,7 @@ msgstr "*OU* un lien vers une page interne au site"
 
 #: coldcms/blocks/link_page.py:39
 msgid "link to an external URL"
-msgstr "Lien vers une page interne du site"
+msgstr "Lien vers une page externe du site"
 
 #: coldcms/blocks/link_page.py:45
 msgid "append to URL"
@@ -86,7 +90,7 @@ msgstr "Cette page redirige vers: %(url)s"
 #: coldcms/blog/models.py:105 coldcms/contact/models.py:93
 #: coldcms/faq/models.py:71 coldcms/generic_page/models.py:88
 #: coldcms/home/models.py:89 coldcms/legal_notice/models.py:32
-#: coldcms/partners/models.py:63 coldcms/simple_page/models.py:31
+#: coldcms/partners/models.py:66 coldcms/simple_page/models.py:31
 msgid "Settings"
 msgstr "Paramètres"
 
@@ -118,13 +122,17 @@ msgstr "Tags"
 msgid "Blog information"
 msgstr "Informations"
 
+#: coldcms/blog/models.py:48
+msgid "Gallery images"
+msgstr "Galerie d'images"
+
 #: coldcms/blog/models.py:50 coldcms/blog/models.py:102
 #: coldcms/contact/models.py:50 coldcms/contact/models.py:90
 #: coldcms/faq/models.py:49 coldcms/faq/models.py:68
 #: coldcms/generic_page/models.py:76 coldcms/generic_page/models.py:85
 #: coldcms/home/models.py:77 coldcms/home/models.py:86
 #: coldcms/legal_notice/models.py:18 coldcms/legal_notice/models.py:29
-#: coldcms/partners/models.py:41 coldcms/partners/models.py:60
+#: coldcms/partners/models.py:44 coldcms/partners/models.py:63
 #: coldcms/simple_page/models.py:18 coldcms/simple_page/models.py:28
 msgid "Content"
 msgstr "Contenu"
@@ -336,13 +344,17 @@ msgstr "Site web du partenaire"
 
 #: coldcms/partners/models.py:29
 msgid "The category of partner (ex: Institution)"
-msgstr "La catégorie du patenaire (ex: Institutionnel)"
+msgstr "La catégorie des partenaires (ex: Institutionnel)"
 
-#: coldcms/partners/models.py:32 coldcms/partners/models.py:70
+#: coldcms/partners/models.py:33 coldcms/partners/models.py:73
 msgid "Partners"
 msgstr "Partenaires"
 
-#: coldcms/partners/models.py:46
+#: coldcms/partners/models.py:37
+msgid "Partners' group"
+msgstr "Groupe de partenaires"
+
+#: coldcms/partners/models.py:49
 msgid "Partners' groups"
 msgstr "Groupes de partenaires"
 
@@ -405,6 +417,7 @@ msgid "Couldn't re-generate page"
 msgstr "Impossible de regénérer la page"
 
 #: coldcms/wagtail_customization/templates/wagtail_customization/confirm_generate_statics.html:3
+#, python-format
 msgid "Re-generate %(title)s"
 msgstr "Re-générer %(title)s"
 
@@ -435,3 +448,12 @@ msgstr "S'identifier à ColdCMS"
 #: coldcms/wagtail_customization/wagtail_hooks.py:22
 msgid "Re-build page"
 msgstr "Re-générer la page"
+
+#~ msgid "Hide Menu"
+#~ msgstr "Masquer le menu"
+
+#~ msgid "Whether to hide the menu bar or not"
+#~ msgstr "Masquer ou non la barre de menu"
+
+#~ msgid "Menu options"
+#~ msgstr "Options du menu"

coldcms/partners/models.py

@@ -29,9 +29,12 @@ class PartnerCategoryBlock(blocks.StructBlock):
         help_text=_("The category of partner (ex: Institution)"),
         required=False,
     )
-    partners = blocks.StreamBlock([("partners", PartnerBlock())], label=_("Partners"))
+    partners = blocks.StreamBlock(
+        [(_("Partners"), PartnerBlock())], label=_("Partners")
+    )
 
     class Meta:
+        label = _("Partners' group")
         icon = "group"
 
 

docs/_static/css/custom.css

+body{
+    color: #000000;
+}
+
+a{
+    color: #9B59B6;
+}
+
+a:visited{
+    color: #9B59B6;
+}
+
+a:hover{
+    color: #d03b3b;
+}
+
+.wy-nav-side {
+    background: #680084;
+}
+
+.wy-side-nav-search{
+    background-color: #680084;
+}
+
+.wy-side-nav-search a{
+    color: #ffffff;
+}
+
+.wy-side-nav-search a:visited{
+    color: #ffffff;
+}
+
+.wy-side-nav-search div.version{
+    color: #ffffff;
+}
+
+.wy-menu-vertical a{
+    color: #ffffff;
+}
+
+.wy-menu-vertical a:hover{
+    background-color: #d299ea;
+    color: #000000;
+}
+
+.wy-menu-vertical li.toctree-l2 a{
+    background-color: #9B59B6;
+    color: #ffffff;
+}
+
+.wy-menu-vertical li.toctree-l2 a:hover{
+    background-color: #d299ea;
+    color: #000000;
+}
+
+.wy-menu-vertical li.toctree-l2.current a{
+    background-color: #efefef ;
+    color: #000000 ;
+}
+
+.wy-nav-top {
+    background: #680084;
+}
+
+.wy-nav-top a{
+    color: #ffffff;
+}
+
+.wy-nav-content-wrap{
+    background: #fcfcfc;
+}
+
+footer > a{
+    text-decoration: underline;
+}
+
+footer {
+    color: #686868;
+}
\ No newline at end of file