Commits

Simon Meers committed bcbcdae

Initial documentation

Comments (0)

Files changed (8)

dbgettext/html.py

         self.attributes = attributes
 
     def is_translatable(self):
-        return self.name in Tag.gettext_inline_tags
+        return self.name.lower() in Tag.gettext_inline_tags
 
 
 def html_gettext(obj, attribute, export=False):

dbgettext/models.py

-class Options(object):
-    """
-    Encapsulates dbgettext options for a given model 
-
-    - attributes: 
-        tuple of names of fields/callables to be translated
-    - html_attributes: 
-        tuple of names of fields/callables with HTML content which should have 
-        translatable content extracted (should not be listed in attributes)
-    - translate_if:
-        dictionary used to filter() queryset 
-    - get_path_identifier:
-        function returning string used to identify object in path to exported 
-        content (given an object)
-    - parent:
-        name of foreign key to parent model, if registered. Affects:
-        - path (path_identifier appended onto parent path)
-        - queryset (object only translated if parent is)
-    - custom_lexicon_rules
-        list of extra custom rules ((regexp, function) tuples) to be applied
-        when parsing HTML -- see html.py
-    - custom_lexicon:
-        complete list of rules ((regexp, function) tuples) for parsing HTML 
-         -- see html.py
-
-    """
-
-    attributes = ()
-    html_attributes = ()
-    translate_if = {}
-    parent = None
-    
-    def get_path_identifier(self, obj):
-        return '%s_%d' % (obj._meta.object_name, obj.id)

dbgettext/registry.py

 from django.db.models.base import ModelBase
-from models import Options
+
+class Options(object):
+    """
+    Encapsulates dbgettext options for a given model 
+
+    - attributes: 
+        tuple of names of fields/callables to be translated
+    - html_attributes: 
+        tuple of names of fields/callables with HTML content which should have 
+        translatable content extracted (should not be listed in attributes)
+    - translate_if:
+        dictionary used to filter() queryset 
+    - get_path_identifier:
+        function returning string used to identify object in path to exported 
+        content (given an object)
+    - parent:
+        name of foreign key to parent model, if registered. Affects:
+        - path (path_identifier appended onto parent path)
+        - queryset (object only translated if parent is)
+    - custom_lexicon_rules
+        list of extra custom rules ((regexp, function) tuples) to be applied
+        when parsing HTML -- see html.py
+    - custom_lexicon:
+        complete list of rules ((regexp, function) tuples) for parsing HTML 
+         -- see html.py
+
+    """
+
+    attributes = ()
+    html_attributes = ()
+    translate_if = {}
+    parent = None
+    
+    def get_path_identifier(self, obj):
+        return '%s_%d' % (obj._meta.object_name, obj.id)
+
 
 # Registration code based on django.contrib.admin.sites
 
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage']
+extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 #html_use_modindex = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False

docs/dbgettext_export.rst

+.. _dbgettext_export:
+
+The ``dbgettext_export`` Management Command
+===========================================
+
+To obtain a fresh export of your translatable strings from registered models, simply run::
+
+    python manage.py dbgettext_export
+
+from your project's root directory.
+
+This will create a hierarchy of static files (stored by default in ``<project_root>/locale/dbgettext``, configurable using the ``DBGETTEXT_PATH`` and ``DBGETTEXT_ROOT`` settings) containing the translatable strings. E.g.::
+
+    locale/dbgettext/myapp/mymodel_1/title.py
+    locale/dbgettext/myapp/mymodel_1/body.py
+    locale/dbgettext/myapp/mymodel_2/title.py
+    locale/dbgettext/myapp/mymodel_2/body.py
+
+You can then simply run::
+
+    python manage.py makemessages (...)
+
+as per usual, and these strings will be catalogued for you together with the rest of the translatable strings from your code and templates.
+
+**Note:** the ``<DBGETTEXT_PATH>/<DBGETTEXT_ROOT>`` directory is purged each time ``dbgettext_export`` is run to ensure that old data (e.g. from deleted objects) does not persist in the catalogue.
+
+The paths and names of the static files are intentionally verbose to provide the translator with the context of the string they are translating. You can customise the path using the ``get_path_identifier`` and ``parent`` attributes of the ``Options`` class -- see :doc:`registration`.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to django-dbgettext's documentation!
-============================================
+django-dbgettext documentation
+==============================
+
+Here lies some basic documentation to get you started with django-dbgettext. The application itself is not overly large or complex, and I recommend perusing the source code for a full understanding.
+
+The premise of django-dbgettext is simple: `gettext <http://www.gnu.org/software/gettext>`_ is already used for translating content from Django's source code and templates, so why not use it for translating database content also? Then the whole process is unified and simplified for translators, and there is no need to provide custom administration interfaces for dynamic content. Simply use the ``dbgettext_export`` `management command <http://docs.djangoproject.com/en/dev/howto/custom-management-commands/>`_ to export the content from the database prior to running `makemessages <http://docs.djangoproject.com/en/dev/topics/i18n/#message-files>`_.
+
+
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-Indices and tables
-==================
+   registration
+   dbgettext_export
+   settings
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
 

docs/registration.rst

+.. _registration:
+
+Registering Models
+==================
+
+Models can be registered for django-dbgettext in a similar fashion to registering `ModelAdmin classes <http://docs.djangoproject.com/en/dev/ref/contrib/admin/#modeladmin-objects>`_ for ``django.contrib.admin``
+
+Simply create a ``gettext.py`` file within your application root directory, import the dbgettext ``registry`` object, and register your Models together with their customised ``dbgettext.models.Options``. For example::
+
+    from dbgettext.registry import registry, Options
+    from myapp.models import MyModel
+
+    class MyModelOptions(Options):
+        attributes = ('title',)
+	html_attributes = ('body',)
+	
+    registry.register(MyModel, MyModelOptions)
+
+That's it. Your ``gettext.py`` files will be automatically imported by django-dbgettext, and registered models will be included when running :doc:`dbgettext_export <dbgettext_export>`.
+
+
+.. _options:
+
+-----------
+``Options``
+-----------
+    
+- ``attributes``: 
+    tuple of names of fields/callables to be translated
+- ``html_attributes``: 
+    tuple of names of fields/callables with HTML content which should have 
+    translatable content extracted (should not be listed in ``attributes``)
+- ``translate_if``:
+    dictionary used to ``filter()`` queryset 
+- ``get_path_identifier``:
+    function returning string used to identify object in path to exported 
+    content (given an object)
+- ``parent``:
+    name of foreign key to parent model, if registered. Affects:
+        - path (path_identifier appended onto parent path)
+        - queryset (object only translated if parent is)
+- ``custom_lexicon_rules``
+    list of extra custom rules ((regexp, function) tuples) to be applied when 
+    parsing HTML -- see html.py
+- ``custom_lexicon``:
+    complete list of rules ((regexp, function) tuples) for parsing HTML -- see 
+    html.py

docs/settings.rst

+.. _settings:
+
+Settings
+========
+
+The following settings can be overridden in your project's ``settings.py``:
+
+* ``DBGETTEXT_PATH``: path (absolute or relative to project root) where :doc:`dbgettext_export <dbgettext_export>` should store its output. Defaults to ``locale``.
+* ``DBGETTEXT_ROOT``: name of directory within ``DBGETTEXT_PATH`` (redundancy to provide protection from auto-purging upon export). Defaults to ``dbgettext``.
+* ``DBGETTEXT_INLINE_TAGS``: tuple of tag names allowed to appear inline within strings extracted from ``html_attributes``. Defaults to ``('b','i','u','em','strong',)``.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.