Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

multilingual docs added to concepts section #1301

Merged
merged 1 commit into from

3 participants

@evildmp
Owner

Note - this also describes a bug or misfeature in the way language prefixes in URLS override both user browser language and the user's choice in language_chooser.

@ojii ojii commented on the diff
docs/concepts/multiple_languages.rst
((2 lines not shown))
+Serving content in multiple languages
+#####################################
+
+**************
+Basic concepts
+**************
+
+django CMS has a sophisticated multilingual capability; it's able to serve
+content in multiple languages, with fallbacks into other languages where
+translations have not been provided, the facility for the user to set the
+preferred language and so on.
+
+How django CMS determines the user's preferred language
+=======================================================
+
+django CMS determines the user's language based on (in order of priority):
@ojii Collaborator
ojii added a note

Maybe add a note that other than the prefix stuff, this is standard django behavior

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ojii
Collaborator

Other than the inline comment, lgtm

@piquadrat piquadrat merged commit 7df50a4 into divio:develop
@evildmp evildmp deleted the evildmp:YAMD branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jun 16, 2012
  1. @evildmp
This page is out of date. Refresh to see the latest.
Showing with 105 additions and 0 deletions.
  1. +104 −0 docs/concepts/multiple_languages.rst
  2. +1 −0  docs/index.rst
View
104 docs/concepts/multiple_languages.rst
@@ -0,0 +1,104 @@
+#####################################
+Serving content in multiple languages
+#####################################
+
+**************
+Basic concepts
+**************
+
+django CMS has a sophisticated multilingual capability; it's able to serve
+content in multiple languages, with fallbacks into other languages where
+translations have not been provided, the facility for the user to set the
+preferred language and so on.
+
+How django CMS determines the user's preferred language
+=======================================================
+
+django CMS determines the user's language based on (in order of priority):
@ojii Collaborator
ojii added a note

Maybe add a note that other than the prefix stuff, this is standard django behavior

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+* the language code prefix in the URL (but see :ref:`the_bug` below)
+* the last language the user chose in the language chooser
+* the language that the browser says its user prefers
+
+How django CMS determines what language to serve
+================================================
+
+Once it has identified a user's language, it will try to accommodate it using the languages set in :setting:`CMS_LANGUAGES`.
+
+If :setting:`CMS_LANGUAGE_FALLBACK` is True, and if the user's preferred
+language is not available for that content, it will use the fallbacks
+specified for the language in :setting:`CMS_LANGUAGE_CONF`.
+
+What django CMS shows in your menus
+===================================
+
+If :setting:`CMS_HIDE_UNTRANSLATED` is ``True`` (the default) then pages that
+aren't translated into the desired language will not appear in the menu.
+
+*****************
+Follow an example
+*****************
+
+It helps to understand how the system behaves by stepping through some actual
+examples.
+
+1. the situation:
+* your browser wants Italian content
+* the CMS is set up to provide content in English and Italian
+* :setting:`CMS_HIDE_UNTRANSLATED` is False
+* the page ``/some/page``
+1. you visit ``/some/page``
+* the content is served in Italian
+* all link URLs (menus etc.) on that page will be prepended with /it
+* the page is served at ``/some/page`` (i.e. no redirection has taken place)
+1. now you select one of those links ``/it/some/other/page`` that is available in Italian
+* Italian content is served
+* the page is served at ``/it/some/other/page``
+1. now you select a link to a page **not** available in Italian
+* the link is still ``/it/some/other/page``
+* you'll get the English version, because Italian's not available
+* the path of the new page is ``/en/some/other/page`` (i.e. it has redirected)
+* some issues (see :ref:`the_bug` below)
+
+ * all links on ``/en/some/other/page`` are prepended with ``/en`` - even if they are available in Italian
+ * if you now visit ``/some/page`` or any other page without using a language prefix, you'll get content in English - even though your browser wants Italian
+
+.. _the_bug:
+
+*********************
+Watch out for the bug
+*********************
+
+What goes wrong
+===============
+
+As soon as you visit any page with a ``/en`` prefix in the path, the system
+sets a ``django_language cookie`` (which will expire when the browser is quit)
+with content "en".
+
+From now on, the system thinks that you want English content.
+
+Note that this could have happened:
+
+* because you chose English in the language selector (good)
+* because you arrived at a /en page from a search engine (possibly bad)
+* because the page you wanted in Italian redirected you to an English one without warning or choice (bad)
+
+.. note::
+ This is an issue the developers are aware of and are working towards fixing.
+
+What should happen
+==================
+
+Your language cookie should only ever get set or changed if:
+
+* you choose a language in the language selector
+* your browser has asked for a language (but this can't override your choice above)
+
+If your cookie contains a particualar language (say, "it"):
+* the content should be served in Italian wherever available
+* links on a page should be to ``/it`` content where available, and fallback where not
+
+When visiting a page only available in English:
+* content will have to be in English
+* links should be to Italian content where possible
View
1  docs/index.rst
@@ -68,6 +68,7 @@ Concepts
concepts/introduction
concepts/menu_system
+ concepts/multiple_languages
**************************
Something went wrong with that request. Please try again.