Merge remote-tracking branch 'origin/master'

docs/admin/management.rst

@@ -16,7 +16,7 @@ add_suggestions <project> <component> <language> <file>
 
 .. django-admin:: add_suggesstions
 
-.. versionaddded:: 2.5
+.. versionadded:: 2.5
 
 Imports translation from the file as a suggestions to given translation. It
 skips translations which are same as existing ones, only different ones are

docs/devel/index.rst

@@ -4,100 +4,9 @@ Application developer guide
 Using Weblate for translating your projects can bring you quite a lot of
 benefits. It's only up to you how much of that you will use.
 
-.. _reports:
+.. toctree::
 
-Activity reports
-----------------
-
-You can check activity reports for translations, project or individual users.
-
-.. image:: ../images/activity.png
-
-.. _promotion:
-
-Promoting the translation
--------------------------
-
-Weblate provides you widgets to share on your website or other sources to
-promote the translation project. It also has a nice welcome page for new contributors
-to give them basic information about the translation. Additionally you can
-share information about translation using Facebook or Twitter. All these
-possibilities can be found on the :guilabel:`Share` tab. Example of status badges
-for Weblate itself are show below.
-
-Shields.IO badge often used to quickly see status of a project:
-
-.. image:: ../images/weblate-shields-badge.*
-    :alt: Translation status
-    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
-
-Small badge often used to quickly see status of a project:
-
-.. image:: ../images/weblate-status-badge.png
-    :alt: Translation status
-    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
-
-Big badge with status details useful for inclusion on a web page:
-
-.. image:: ../images/weblate-287x66-white.png
-    :alt: Translation status
-    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
-
-Small badge with status useful for inclusion on a web page:
-
-.. image:: ../images/weblate-88x31-grey.png
-    :alt: Translation status
-    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
-
-All these badges come with links to simple page which explains users how to
-translate using Weblate:
-
-.. image:: ../images/engage.png
-
-Reviewing source strings
-------------------------
-
-Source strings checks
-+++++++++++++++++++++
-
-Weblate includes quite a lot of :ref:`checks`. Some of them also focus on
-quality of source strings. These can give you some hints for making strings
-easier to translate. You can check failing source checks on :guilabel:`Source`
-tab of every component.
-
-Failing checks on translation
-+++++++++++++++++++++++++++++
-
-On the other side, failing translation checks might also indicate problem in
-the source strings. Translators often tend to fix some mistakes in translation
-instead of reporting it - typical example is missing full stop at the end of
-sentence, but there are more such cases.
-
-Reviewing all failing checks on your translation can bring you valuable
-feedback for improving source strings as well.
-
-String comments
-+++++++++++++++
-
-Weblate allows translators to comment on both translation and source strings.
-Each :ref:`component` can be configured to receive such comments on email
-address and sending this to developers mailing list is usually best approach.
-This way you can monitor when translators find problems and fix them quickly.
-
-.. _adding-translation:
-
-Adding new translations
------------------------
-
-Weblate can add new language files to your project automatically for most of
-the :ref:`formats`. This feature needs to be enabled in the :ref:`component`.
-In case this is not enabled (or available for your file format) the files have
-to be added manually to the VCS.
-
-Weblate will automatically detect new languages which are added to the VCS
-repository and makes them available for translation. This makes adding new
-translations incredibly easy:
-
-1. Add the translation file to VCS.
-2. Let Weblate update the repository (usually set up automatically, see
-   :ref:`update-vcs`).
+    starting
+    translations
+    review
+    share

docs/devel/review.rst

+Reviewing source strings
+========================
+
+.. _reports:
+
+Activity reports
+----------------
+
+You can check activity reports for translations, project or individual users.
+
+.. image:: ../images/activity.png
+
+Source strings checks
+---------------------
+
+Weblate includes quite a lot of :ref:`checks`. Some of them also focus on
+quality of source strings. These can give you some hints for making strings
+easier to translate. You can check failing source checks on :guilabel:`Source`
+tab of every component.
+
+Failing checks on translation
+-----------------------------
+
+On the other side, failing translation checks might also indicate problem in
+the source strings. Translators often tend to fix some mistakes in translation
+instead of reporting it - typical example is missing full stop at the end of
+sentence, but there are more such cases.
+
+Reviewing all failing checks on your translation can bring you valuable
+feedback for improving source strings as well.
+
+String comments
+---------------
+
+Weblate allows translators to comment on both translation and source strings.
+Each :ref:`component` can be configured to receive such comments on email
+address and sending this to developers mailing list is usually best approach.
+This way you can monitor when translators find problems and fix them quickly.
+

docs/devel/share.rst

+.. _promotion:
+
+Promoting the translation
+=========================
+
+Weblate provides you widgets to share on your website or other sources to
+promote the translation project. It also has a nice welcome page for new contributors
+to give them basic information about the translation. Additionally you can
+share information about translation using Facebook or Twitter. All these
+possibilities can be found on the :guilabel:`Share` tab. Example of status badges
+for Weblate itself are show below.
+
+Shields.IO badge often used to quickly see status of a project:
+
+.. image:: ../images/weblate-shields-badge.*
+    :alt: Translation status
+    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
+
+Small badge often used to quickly see status of a project:
+
+.. image:: ../images/weblate-status-badge.png
+    :alt: Translation status
+    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
+
+Big badge with status details useful for inclusion on a web page:
+
+.. image:: ../images/weblate-287x66-white.png
+    :alt: Translation status
+    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
+
+Small badge with status useful for inclusion on a web page:
+
+.. image:: ../images/weblate-88x31-grey.png
+    :alt: Translation status
+    :target: https://hosted.weblate.org/engage/weblate/?utm_source=widget
+
+All these badges come with links to simple page which explains users how to
+translate using Weblate:
+
+.. image:: ../images/engage.png

docs/devel/starting.rst

+Starting with internationalization
+==================================
+
+You have a project and want to to translate it into several languages? This
+guide will help you to do so. We will showcase several usual situations, but
+most of the examples are generic and can be applied to other scenarios as
+well.
+
+Before translating any software, you should realize that languages around
+world are really different and you should not make any assumption based on
+your experience. For most of languages it will look weird if you try to
+concatenate sentence out of translated segments. You also should properly
+handle plural forms because many languages have complex rules for that and the
+internationalization framework you end up using should support this. 
+
+Last but not least, sometimes it might be necessary to add some context to the
+translated string. Imagine translator would get string ``Sun`` to translate.
+Without context most people would translate that as our closest star, but you
+might be actually used as abbreviated name of day of week...
+
+
+Translating software using GNU Gettext
+--------------------------------------
+
+`GNU Gettext`_ is one of the most widely used tool for internationalization of
+free software. It provides simple yet flexible way to localize the software.
+It has great support for plurals, it can add further context to the translated
+string and there are quite a lot of tools built around it. Of course it has
+great support in Weblate (see :ref:`gettext` file format description).
+
+.. note::
+   
+    If you are about to use it in proprietary software, please consult
+    licensing first, it might not be suitable for you.
+
+GNU Gettext can be used from variety of languages (C, Python, PHP, Ruby,
+Javascript and much more) and usually the UI frameworks already come with some
+support for it. The standard usage is though the `gettext()` function call,
+which is often aliased to `_()` to make the code simpler and easier to read.
+
+Additionally it provides `pgettext()` call to provide additional context to
+translators and `ngettext()` which can handle plural types as defined for
+target language.
+
+The simple program in C using Gettext might look like following:
+
+.. code-block:: c
+
+    #include <libintl.h>
+    #include <locale.h>
+    #include <stdio.h>
+    #include <stdlib.h>
+
+    int main(void)
+    {
+        int count = 1;
+        setlocale(LC_ALL, "");
+        bindtextdomain("hello", "/usr/share/locale");
+        textdomain("hello");
+        printf( 
+            ngettext( 
+                "Orangutan has %d banana.\n", 
+                "Orangutan has %d bananas.\n", 
+                count 
+            ), 
+            count 
+        );
+        printf("%s\n", gettext("Thank you for using Weblate."));
+        exit(0);
+    }
+
+Once you have code using the gettext calls, you can use :program:`xgettext` to
+extract message from it:
+
+.. code-block:: console
+
+    $ xgettext main.c -o po/hello.pot
+
+This creates template file, which you can use for starting new translations
+(using :program:`msginit`) or updating existing ones after code change (you
+would use :program:`msgmerge` for that). The resulting file is simply
+structured text file:
+
+.. code-block:: po
+
+    # SOME DESCRIPTIVE TITLE.
+    # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+    # This file is distributed under the same license as the PACKAGE package.
+    # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+    #
+    #, fuzzy
+    msgid ""
+    msgstr ""
+    "Project-Id-Version: PACKAGE VERSION\n"
+    "Report-Msgid-Bugs-To: \n"
+    "POT-Creation-Date: 2015-10-23 11:02+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"
+    "Language: \n"
+    "MIME-Version: 1.0\n"
+    "Content-Type: text/plain; charset=CHARSET\n"
+    "Content-Transfer-Encoding: 8bit\n"
+    "Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;\n"
+    
+    #: main.c:14
+    #, c-format
+    msgid "Orangutan has %d banana.\n"
+    msgid_plural "Orangutan has %d bananas.\n"
+    msgstr[0] ""
+    msgstr[1] ""
+    
+    #: main.c:20
+    msgid "Thank you for using Weblate."
+    msgstr ""
+
+The each ``msgid`` line defines string to translate, the special empty string
+in the beginning is the file header containing metadata about the translation.
+
+With the template in place, we can start first translation:
+
+.. code-block:: console
+
+    $ msginit -i po/hello.pot -l cs --no-translator -o po/cs.po
+    Created cs.po.
+
+The just created :file:`cs.po` has already some information filled in. Most
+importantly it got proper plural forms definition for chosen language and you
+can see number of plurals have changed according to that:
+
+.. code-block:: po
+    
+    # Czech translations for PACKAGE package.
+    # Copyright (C) 2015 THE PACKAGE'S COPYRIGHT HOLDER
+    # This file is distributed under the same license as the PACKAGE package.
+    # Automatically generated, 2015.
+    #
+    msgid ""
+    msgstr ""
+    "Project-Id-Version: PACKAGE VERSION\n"
+    "Report-Msgid-Bugs-To: \n"
+    "POT-Creation-Date: 2015-10-23 11:02+0200\n"
+    "PO-Revision-Date: 2015-10-23 11:02+0200\n"
+    "Last-Translator: Automatically generated\n"
+    "Language-Team: none\n"
+    "Language: cs\n"
+    "MIME-Version: 1.0\n"
+    "Content-Type: text/plain; charset=ASCII\n"
+    "Content-Transfer-Encoding: 8bit\n"
+    "Plural-Forms: nplurals=3; plural=(n==1) ? 0 : (n>=2 && n<=4) ? 1 : 2;\n"
+    
+    #: main.c:14
+    #, c-format
+    msgid "Orangutan has %d banana.\n"
+    msgid_plural "Orangutan has %d bananas.\n"
+    msgstr[0] ""
+    msgstr[1] ""
+    msgstr[2] ""
+    
+    #: main.c:20
+    msgid "Thank you for using Weblate."
+    msgstr ""
+
+To import such translation into Weblate, all you need to define are following
+fields when creating component (see :ref:`component` for detailed description
+of the fields):
+
+=============================== ==================================================
+Field                           Value
+=============================== ==================================================
+Source code repository          URL of the VCS repository with your project
+
+File mask                       ``po/*.po``
+
+Base file for new translations  ``po/hello.pot``
+
+File format                     Choose :guilabel:`Gettext PO file`
+
+New language                    Choose :guilabel:`Automatically add language file`
+=============================== ==================================================
+
+And that's it, you're now ready to start translating your software!
+
+.. seealso::
+
+    You can find more complex of using Gettext in the weblate-hello project on
+    GitHub: <http://github.com/nijel/weblate-hello>.
+
+Translating documentation using Sphinx
+--------------------------------------
+
+`Sphinx`_ is a tool for creating beautiful documentation. It uses simple
+reStructuredText syntax and can generate output in many formats. If you're
+looking for an example, this documentation is also build using it. The very
+useful companion for using Sphinx is the `Read the Docs`_ service, which will
+build and publish your documentation for free.
+
+I will not focus on writing documentation itself, you you need guidance with
+that, just follow instructions on the `Sphinx`_ website. Once you have
+documentation ready, translating it is quite easy as Sphinx comes with support
+for this and it is quite nicely covered in their
+`Internationalization Quick Guide`_.  It's matter of few configuration
+directives and invoking of the ``sphinx-intl`` tool.
+
+If you are using Read the Docs service, you can start building translated
+documentation on the Read the docs. Their `Localization of Documentation`_
+covers pretty much everything you need - creating another project, set it's
+language and link it from master project as a translation.
+
+Now all you need is translating the documentation content. As Sphinx splits
+the translation files per source file, you might end up with dozen of files,
+which might be challenging to import using the Weblate's web interface. For
+that reason, there is :djadmin:`import_project` management command.
+
+Depending on exact setup, importing of the translation might look like:
+
+.. code-block:: console
+
+    $ ./manage.py import_project --name-template 'Documentation: %s' \
+        --file-format po \
+        project https://github.com/project/docs.git master \
+        'docs/locale/*/LC_MESSAGES/**.po'
+
+.. seealso::
+
+    The `Odorik`_ python module documentation is built using Sphinx, Read the
+    Docs and translated using Weblate.
+
+.. _Odorik: https://github.com/nijel/odorik/
+.. _GNU Gettext: http://www.gnu.org/software/gettext/
+.. _Sphinx: http://sphinx-doc.org/
+.. _Read the Docs: https://readthedocs.org/
+.. _Internationalization Quick Guide: http://sphinx-doc.org/latest/intl.html#quick-guide
+.. _Localization of Documentation: https://docs.readthedocs.org/en/latest/localization.html

docs/devel/translations.rst

+Managing translations
+=====================
+
+.. _adding-translation:
+
+Adding new translations
+-----------------------
+
+Weblate can add new language files to your project automatically for most of
+the :ref:`formats`. This feature needs to be enabled in the :ref:`component`.
+In case this is not enabled (or available for your file format) the files have
+to be added manually to the VCS.
+
+Weblate will automatically detect new languages which are added to the VCS
+repository and makes them available for translation. This makes adding new
+translations incredibly easy:
+
+1. Add the translation file to VCS.
+2. Let Weblate update the repository (usually set up automatically, see
+   :ref:`update-vcs`).

weblate/html/mail/new_language.html

@@ -16,7 +16,7 @@
 </p>
 
 <p>
-{% doc_url 'devel/index' 'adding-translation' as doc_url %}
+{% doc_url 'devel/translations' 'adding-translation' as doc_url %}
 {% blocktrans %}More information on adding new language files is available in <a href="{{ doc_url }}">the documentation</a>.{% endblocktrans %}
 </p>
 

weblate/html/mail/new_language.txt

@@ -4,7 +4,7 @@
 
 {% trans "Please add the language file to VCS, Weblate will automatically discover it on next update." %}
 
-{% trans "More information on adding new language files is available in the documentation:" %} {% documentation 'devel/index' 'adding-translation' %}
+{% trans "More information on adding new language files is available in the documentation:" %} {% documentation 'devel/translations' 'adding-translation' %}
 
 {% trans "Requested language:" %}