From dccb47178bef5feaae413854f764cb16dfb7d4d2 Mon Sep 17 00:00:00 2001
From: Karl Hobley <karl@torchbox.com>
Date: Tue, 15 Jul 2014 10:38:50 +0100
Subject: [PATCH] Added tutorial for creating multilingual sites

---
 docs/index.rst              |   1 +
 docs/multilingual_sites.rst | 145 ++++++++++++++++++++++++++++++++++++
 2 files changed, 146 insertions(+)
 create mode 100644 docs/multilingual_sites.rst

diff --git a/docs/index.rst b/docs/index.rst
index 2ab429eb62..582e5aa826 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,7 @@ It supports Django 1.6.2+ on Python 2.6, 2.7, 3.2, 3.3 and 3.4. Django 1.7 suppo
    search/index
    form_builder
    model_recipes
+   multilingual_sites
    advanced_topics
    deploying
    performance
diff --git a/docs/multilingual_sites.rst b/docs/multilingual_sites.rst
new file mode 100644
index 0000000000..f8f9e1f73d
--- /dev/null
+++ b/docs/multilingual_sites.rst
@@ -0,0 +1,145 @@
+===========================
+Creating multilingual sites
+===========================
+
+This tutorial will show you a method of creating multilingual sites in Wagtail.
+
+Currently, Wagtail doesn't support multiple languages in the same page. The recommended way of creating multilingual websites in Wagtail at the moment is to create one section of your website for each language.
+
+For example::
+
+    /
+        en/
+            about/
+            contact/
+        fr/
+            about/
+            contact/
+
+
+The root page
+=============
+
+The root page (``/``) should detect the browsers language and forward them to the correct language homepage (``/en/``, ``/fr/``). This page should sit at the site root (where the homepage would normally be).
+
+We must set Djangos ``LANGUAGES`` setting so we don't redirect non English/French users to pages that don't exist.
+
+
+.. code-block:: python
+
+    # settings.py
+    LANGUAGES = (
+        ('en', _("English")),
+        ('fr', _("French")),
+    )
+
+    # models.py
+    from django.utils import translation
+    from django.http import HttpResponseRedirect
+
+    from wagtail.wagtailcore.models import Page
+
+
+    class LanguageRedirectionPage(Page):
+
+        def serve(self, request):
+            # This will only return a language that is in the LANGUAGES Django setting
+            language = translation.get_language_from_request(request)
+
+            return HttpResponseRedirect(self.url + language + '/')
+
+
+Linking pages together
+======================
+
+It may be useful to link different versions of the same page together to allow the user to easily switch between languages. But we don't want to increse the burdon on the editor too much so ideally, editors should only need to link one of the pages to the other versions and the links between the other versions should be created implicitly.
+
+As this behaviour needs to be added to all page types that would be translated, its best to put this behaviour in a mixin.
+
+Heres an example of how this could be implemented (with English as the main language and French/Spanish as alternative languages):
+
+.. code-block:: python
+
+    class TranslatablePageMixin(models.Model):
+        # One link for each alternative language
+        # These should only be used on the main language page (english)
+        french_link = models.ForeignKey(Page, null=True, on_delete=models.SET_NULL, blank=True, related_name='+')
+        spanish_link = models.ForeignKey(Page, null=True, on_delete=models.SET_NULL, blank=True, related_name='+')
+
+        def get_language(self):
+            """
+            This returns the language code for this page.
+            """
+            # Look through ancestors of this pages for its language homepage
+            # The language homepage is located at depth 3 
+            language_homepage = self.get_ancestors(inclusive=True).get(depth=3)
+
+            return language_homepage.slug
+
+
+        # Method to find the main language version of this page
+        # This works by reversing the above links
+
+        def english_page(self):
+            """
+            This finds the english version of this page
+            """
+            language = self.get_language()
+
+            if language == 'en':
+                return self
+            elif language == 'fr':
+                return type(self).objects.filter(french_link=self).first().specific
+            elif language == 'es':
+                return type(self).objects.filter(spanish_link=self).first().specific
+
+
+        # We need a method to find a version of this page for each alternative language.
+        # These all work the same way. They firstly find the main version of the page
+        # (english), then from there they can just follow the link to the correct page.
+
+        def french_page(self):
+            """
+            This finds the french version of this page
+            """
+            english_page = self.english_page()
+
+            if english_page and english_page.french_link:
+                return english_page.french_link.specific
+
+        def spanish_page(self):
+            """
+            This finds the spanish version of this page
+            """
+            english_page = self.english_page()
+
+            if english_page and english_page.spanish_link:
+                return english_page.spanish_link.specific
+
+        class Meta:
+            abstract = True
+
+
+    class AboutPage(Page, TranslatablePageMixin):
+        ...
+
+
+    class ContactPage(Page, TranslatablePageMixin):
+        ...
+
+
+You can make use of these methods in your template by doing:
+
+.. code-block:: django
+
+    {% if self.english_page and self.get_langage != 'en' %}
+        <a href="{{ self.english_page.url }}">{% trans "View in English" %}</a>
+    {% endif %}
+
+    {% if self.french_page and self.get_langage != 'fr' %}
+        <a href="{{ self.french_page.url }}">{% trans "View in French" %}</a>
+    {% endif %}
+
+    {% if self.spanish_page and self.get_langage != 'es' %}
+        <a href="{{ self.spanish_page.url }}">{% trans "View in Spanish" %}</a>
+    {% endif %}