Skip to content
Browse files

docs

  • Loading branch information...
1 parent 1edf564 commit fedc753bbfbd4978280f863fcf8a987a96ea664b @digi604 digi604 committed
View
6 cms/conf/__init__.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
from django.conf import settings
-from patch import post_patch, post_patch_check
+from patch import post_patch, post_patch_check, pre_patch
import warnings
@@ -9,7 +9,7 @@ def patch_settings():
"""Merge settings with global cms settings, so all required attributes
will exist. Never override, just append non existing settings.
- Also check for setting inconstistence if settings.DEBUG
+ Also check for setting inconsistencies if settings.DEBUG
"""
if patch_settings.ALREADY_PATCHED:
return
@@ -24,6 +24,8 @@ def patch_settings():
from cms.conf import global_settings
# patch settings
+ pre_patch()
+
# merge with global cms settings
for attr in dir(global_settings):
if attr == attr.upper() and not hasattr(settings, attr):
View
4 cms/conf/global_settings.py
@@ -95,7 +95,7 @@
# 'public': False,
# }
# ],
-# 'defaults': {
+# 'default': {
# 'fallbacks': ['en', 'de', 'fr'],
# 'redirect_on_fallback':True,
# 'public': False,
@@ -103,7 +103,7 @@
# }
#}
-CMS_LANGUAGES = {}
+#CMS_LANGUAGES = {}
CMS_SITE_CHOICES_CACHE_KEY = 'CMS:site_choices'
View
52 cms/conf/patch.py
@@ -4,9 +4,16 @@
from django.utils.translation import ugettext_lazy as _
from sekizai.helpers import validate_template
+def pre_patch():
+ """Patch settings for dynamic defaults"""
+ if not getattr(settings, 'CMS_LANGUAGES', False):
+ settings.CMS_LANGUAGES = {settings.SITE_ID:[]}
+ for code, name in settings.LANGUAGES:
+ lang = {'code':code, 'name':_(name)}
+ settings.CMS_LANGUAGES[settings.SITE_ID].append(lang)
def post_patch():
- """Patch settings after global are adde
+ """Patch settings after global are added
"""
if settings.CMS_TEMPLATE_INHERITANCE:
# Append the magic inheritance template
@@ -47,27 +54,28 @@ def post_patch_check():
% template[0]
)
VALID_LANG_PROPS = ['code', 'name', 'fallbacks', 'hide_untranslated', 'redirect_on_fallback', 'public']
-
- for site in settings.CMS_LANGUAGES.keys():
- try:
- int(site)
- except ValueError:
- if not site =="default":
- raise ImproperlyConfigured("CMS_LANGUAGES can only be filled with integers (site ids) and 'default' for\n"
- " default values. %s is not a valid key." % site)
- for lang in settings.CMS_LANGUAGES[site]:
- if site == "default":
- if lang not in VALID_LANG_PROPS:
- raise ImproperlyConfigured("CMS_LANGUAGES has an invalid property on the site %(site)s and language %(language)s: %(property)s" % {'site':site, 'language':lang['code'], 'property':key})
- continue
- if not "code" in lang.keys():
- raise ImproperlyConfigured("CMS_LANGUAGES has language without a 'code' property")
- if not 'name' in lang.keys():
- raise ImproperlyConfigured("CMS_LANGUAGES has a language without a 'name' property")
- for key in lang.keys():
- if key not in VALID_LANG_PROPS:
- raise ImproperlyConfigured("CMS_LANGUAGES has an invalid property on the site %(site)s and language %(language)s: %(property)s" % {'site':site, 'language':lang['code'], 'property':key})
-
+ try:
+ for site in settings.CMS_LANGUAGES.keys():
+ try:
+ int(site)
+ except ValueError:
+ if not site =="default":
+ raise ImproperlyConfigured("CMS_LANGUAGES can only be filled with integers (site ids) and 'default' for\n"
+ " default values. %s is not a valid key." % site)
+ for lang in settings.CMS_LANGUAGES[site]:
+ if site == "default":
+ if lang not in VALID_LANG_PROPS:
+ raise ImproperlyConfigured("CMS_LANGUAGES has an invalid property on the site %(site)s and language %(language)s: %(property)s" % {'site':site, 'language':lang['code'], 'property':key})
+ continue
+ if not "code" in lang.keys():
+ raise ImproperlyConfigured("CMS_LANGUAGES has language without a 'code' property")
+ if not 'name' in lang.keys():
+ raise ImproperlyConfigured("CMS_LANGUAGES has a language without a 'name' property")
+ for key in lang.keys():
+ if key not in VALID_LANG_PROPS:
+ raise ImproperlyConfigured("CMS_LANGUAGES has an invalid property on the site %(site)s and language %(language)s: %(property)s" % {'site':site, 'language':lang['code'], 'property':key})
+ except:
+ raise ImproperlyConfigured("CMS_LANGUAGES has changed. Please refer to the docs.")
View
12 docs/advanced/i18n.rst
@@ -66,15 +66,15 @@ Example:
{% page_language_url "de" %}
-*********************
-CMS_HIDE_UNTRANSLATED
-*********************
+******************
+hide_unstranslated
+******************
-If you put :setting:`CMS_HIDE_UNTRANSLATED` to ``False`` in your
-``settings.py`` all pages will be displayed in all languages even if they are
+If you add a default directive to your :setting:`CMS_LANGUAGES` with a :setting:`hide_unstranslated` to ``False``
+all pages will be displayed in all languages even if they are
not translated yet.
-If :setting:`CMS_HIDE_UNTRANSLATED` is ``True`` in your ``settings.py``
+If `hide_untranslated` is ``True`` in your :setting:`CMS_LANGUAGES`
and you are on a page that doesn't yet have an English translation and you view
the German version then the language chooser will redirect to ``/``. The same
goes for urls that are not handled by the cms and display a language chooser.
View
84 docs/concepts/multiple_languages.rst
@@ -14,10 +14,10 @@ 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):
+django CMS determines the user's language the same way Django does it.
-* 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 code prefix in the URL
+* the last language the user chose in the language chooser (cookie).
* the language that the browser says its user prefers
It uses the django built in capabilities for this.
@@ -27,85 +27,13 @@ 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
+If :setting:`fallbacks` is set, 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`.
+specified for the language in :setting:`CMS_LANGUAGES`.
What django CMS shows in your menus
===================================
-If :setting:`CMS_HIDE_UNTRANSLATED` is ``True`` (the default) then pages that
+If :setting:`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.
-
-#. 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``
-
-#. 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)
-
-#. 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``
-
-#. 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
142 docs/getting_started/configuration.rst
@@ -208,94 +208,128 @@ Currently the following variables are available:
I18N and L10N
*************
-.. setting:: CMS_HIDE_UNTRANSLATED
-
-CMS_HIDE_UNTRANSLATED
-=====================
-
-Default: ``True``
-
-By default django CMS hides menu items that are not yet translated into the
-current language. With this setting set to False they will show up anyway.
-
.. setting:: CMS_LANGUAGES
CMS_LANGUAGES
=============
-Default: Value of :setting:`django:LANGUAGES`
+Default: Value of :setting:`django:LANGUAGES` converted to this format
Defines the languages available in django CMS.
Example::
- CMS_LANGUAGES = (
- ('fr', gettext('French')),
- ('de', gettext('German')),
- ('en', gettext('English')),
- )
+ CMS_LANGUAGES = {
+ 1: [
+ {
+ 'code': 'en',
+ 'name': gettext('English'),
+ 'fallbacks': ['de', 'fr'],
+ 'public': True,
+ 'hide_untranslated': True,
+ 'redirect_on_fallback':False,
+ },
+ {
+ 'code': 'de',
+ 'name': gettext('Deutsch'),
+ 'fallbacks': ['en', 'fr'],
+ 'public': True,
+ },
+ {
+ 'code': 'fr',
+ 'name': gettext('French'),
+ 'public': False,
+ },
+ ],
+ 2: [
+ {
+ 'code': 'nl',
+ 'name': gettext('Dutch'),
+ 'public': True,
+ 'fallbacks': ['en'],
+ },
+ ],
+ 'default': {
+ 'fallbacks': ['en', 'de', 'fr'],
+ 'redirect_on_fallback':True,
+ 'public': False,
+ 'hide_untranslated': False,
+ }
+ }
.. note:: Make sure you only define languages which are also in :setting:`django:LANGUAGES`.
-.. setting:: CMS_LANGUAGE_FALLBACK
+CMS_LANGUAGES has different options where you can granular define how different languages behave.
-CMS_LANGUAGE_FALLBACK
-=====================
+On the first level you can define SITE_IDs and default values. In the example above we define two sites. The first site
+has 3 languages (English, German and French) and the second site has only Dutch. The `default` node defines
+default behavior for all languages. You can overwrite the default settings with language specific properties.
+For example we define `hide_untranslated` as False globally. The English language overwrites this behavior.
-Default: ``True``
+Every language node needs at least a `code` and a `name` property. `code` is the iso 2 code for the language. And
+name is the English name of the language.
-This will redirect the browser to the same page in another language if the
-page is not available in the current language.
+.. note:: With a gettext() lambda function you can make language names translatable. To enable this add
+ `gettext = lambda s: s` at the beginning of your settings file
-.. setting:: CMS_LANGUAGE_CONF
+What are the properties a language node can have?
-CMS_LANGUAGE_CONF
-=================
+.. setting::code
-Default: ``{}``
+code
+----
-Language fallback ordering for each language.
+String. Iso 2 code of the language.
-Example::
+Example: ``"en"``.
- CMS_LANGUAGE_CONF = {
- 'de': ['en', 'fr'],
- 'en': ['de'],
- }
+.. note:: Is required for every language.
-.. setting:: CMS_SITE_LANGUAGES
+name
+----
+String. The English name of the language.
-CMS_SITE_LANGUAGES
-==================
+.. note:: Is required for every language.
-Default: ``{}``
+.. setting::public
-If you have more than one site and :setting:`CMS_LANGUAGES` differs between
-the sites, you may want to fill this out so that when you switch between sites
-in the admin you only get the languages available to that particular site.
+public
+------
+Is this language accessible in the frontend? For example, if you decide you want to add a new language to your page
+but don't want to show it to the world yet.
-Example::
+Type: Boolean
+Default: ``True``
- CMS_SITE_LANGUAGES = {
- 1:['en','de'],
- 2:['en','fr'],
- 3:['en'],
- }
+.. setting::fallbacks
-.. setting:: CMS_FRONTEND_LANGUAGES
+fallbacks
+---------
-CMS_FRONTEND_LANGUAGES
-======================
+A list of languages that are used if a page is not translated yet. The ordering is relevant.
-Default: Value of :setting:`CMS_LANGUAGES`
+Example: ``['de', 'fr']``
+Default: ``[]``
-A list of languages django CMS uses in the frontend. For example, if
-you decide you want to add a new language to your page but don't want to
-show it to the world yet.
+.. setting::hide_untranslated
-Example::
+hide_untranslated
+-----------------
+Should untranslated pages be hidden in the menu?
+
+Type: Boolean
+Default: ``True``
+
+.. setting::redirect_on_fallback
+
+redirect_on_fallback
+--------------------
+
+If a page is not available should there be a redirect to a language that is, or should the content be displayed
+in the other language in this page?
- CMS_FRONTEND_LANGUAGES = ("de", "en", "pt-BR")
+Type: Boolean
+Default:``True``
**************

0 comments on commit fedc753

Please sign in to comment.
Something went wrong with that request. Please try again.