More docs for settings migrations

docs/developers/settings.rst

@@ -52,10 +52,43 @@ Each dict in ``settings`` tuple should define following keys:
 * **field_extra** - dict that defines extra attributes of form field. For "select", "radio" and "checkbox" fields this dict should contain "choices" key with tuple of tuples that will be used for choices in input. For "string" settings you can define "min_length" and "max_length" extra specifying minmal and maximal lenght of entered text. For integer settings you can specify minimal and maximal range in which value should fall by "min_value" and "max_value".
 
 
+.. note::
+   If you wish to make your names and messages translateable, you should use ``ugettext_lazy`` function provided by Misago instead of Django one. This function is defined in ``misago.core.migrationutils`` module and differs from Django one by the fact that it preserves untranslated message on its ``message`` attribute.
+
+   For your convience ``migrate_settings_group`` triess to switch translation messages with their "message" attribute when it writes to database and thus making their translation to new languages in future possible.
+
+
 with_conf_models
 ----------------
 
+.. function:: with_conf_models(migration, this_migration=None)
+
+South migrations define special ``models`` attribute that holds dict representing structure of database at time of migration execution. This dict will by default contain only your apps models. To add settings models that ``migrate_settings_group`` requires to work, you have to use ``with_conf_models`` function. This function accepts two arguments:
+
+* **migration** - name of migration in ``misago.conf`` app containing models definitions current for the time of your data migration.
+* **this_migration** - dict with model definitions for this migration.
+
+In addition to this, make sure that your migration ``depends_on`` attribute defines dependency on migration from ``misago.conf`` app::
+
+    class Migration(DataMigration):
+
+    	# Migration code...
+
+        models = with_conf_models('0001_initial', {
+        	# This migration models
+        })
+
+        depends_on = (
+            ("conf", "0001_initial"),
+        )
+
+
+delete_settings_cache
+---------------------
+
+.. function:: delete_settings_cache()
 
+If you have used ``migrate_settings_group`` function in your migration, make sure to call ``delete_settings_cache`` at its end to flush settings caches.
 
 
 Misago Settings Reference
@@ -80,7 +113,7 @@ avatars_types
 
 List of avatar sources available to users:
 
-* **gravatar** -Gravatar.
+* **gravatar** - Gravatar.
 * **upload** - avatar uploads.
 * **gallery** - predefined gallery.
 

misago/conf/migrationutils.py

@@ -3,6 +3,7 @@ from importlib import import_module
 from misago.conf.dbsettings import CACHE_KEY
 from misago.conf.hydrators import dehydrate_value
 from misago.core.cache import cache as default_cache
+from misago.core.migrationutils import original_message
 try:
     import cPickle as pickle
 except ImportError:
@@ -54,8 +55,8 @@ def migrate_settings_group(orm, group_fixture, old_group_key=None):
     # Update group's attributes
 
     group.key = group_fixture['key']
-    group.name = group_fixture['name']
-    group.description = group_fixture.get('description')
+    group.name = original_message(group_fixture['name'])
+    group.description = original_message(group_fixture.get('description'))
     group.save()
 
     # Delete groups settings and make new ones
@@ -67,6 +68,20 @@ def migrate_settings_group(orm, group_fixture, old_group_key=None):
         setting_fixture['group'] = group
         setting_fixture['order'] = order
 
+        setting_fixture['name'] = original_message(setting_fixture['name'])
+        setting_fixture['description'] = original_message(
+            setting_fixture.get('description'))
+
+        if (setting_fixture.get('field_extra') and
+                setting_fixture.get('field_extra').get('choices')):
+            untranslated_choices = setting_fixture['field_extra']['choices']
+            translated_choices = []
+            if untranslated_choices != '#TZ#':
+                for value, name in untranslated_choices:
+                    translated_choices.append((value, original_message(name)))
+            setting_fixture['field_extra']['choices'] = tuple(
+                translated_choices)
+
         try:
             value = custom_settings_values[setting_fixture['setting']]
         except KeyError:

misago/core/migrationutils.py

@@ -15,6 +15,13 @@ def ugettext_lazy(string):
     return t
 
 
+def original_message(string):
+    try:
+        return unicode(string.message)
+    except AttributeError:
+        return unicode(string)
+
+
 def with_core_models(migration, this_migration=None):
     module_name = 'misago.core.migrations.%s' % migration
     migration_module = import_module(module_name)