diff --git a/pyramid_formalchemy/actions.py b/pyramid_formalchemy/actions.py
index ade111a..b939519 100644
--- a/pyramid_formalchemy/actions.py
+++ b/pyramid_formalchemy/actions.py
@@ -6,7 +6,52 @@ from pyramid_formalchemy.i18n import get_localizer
 from pyramid_formalchemy.i18n import _
 import functools
 
+__doc__ = """
+pyramid_formalchemy provide a way to use some ``actions`` in your template.
+Action are basically links or input button.
+
+By default there is only one category ``buttons`` which are the forms buttons
+but you can add some categories like this::
+
+    >>> from pyramid_formalchemy.views import ModelView
+    >>> class MyView(ModelView)
+    ...     # keep default action categorie and add the custom_actions categorie
+    ...     actions_categories = ('buttons', 'custom_actions')
+    ...     # update the default actions for all models
+    ...     defaults_actions = actions_categories.defaults_actions.copy()
+    ...     defaults_actions.update(edit_custom_actions=myactions)
+
+Where ``myactions`` is an :class:`~pyramid_formalchemy.actions.Actions` instance
+
+You can also customize the actions per Model::
+
+    >>> class MyArticle(Base):
+    ...     edit_buttons = Actions()
+
+The available actions are:
+
+- listing
+
+- new
+
+- edit
+
+But you can add your own::
+
+    >>> from pyramid_formalchemy.views import ModelView
+    >>> from pyramid_formalchemy import actions
+    >>> class MyView(ModelView)
+    ...     actions.action()
+    ...     def extra(self):
+    ...         # do stuff
+    ...         return self.render(**kw)
+
+Then pyramid_formalchemy will try to load some ``extra_buttons`` actions.
+"""
+
 def action(name=None):
+    """A decorator use to add some actions to the request.
+    """
     def wrapper(func):
         action = name or func.__name__
         @functools.wraps(func)
@@ -26,7 +71,8 @@ def action(name=None):
 
 
 class Action(object):
-    """A model action is used to add some action in model views::
+    """A model action is used to add some action in model views. The content
+    and alt parameters should be a ``TranslationString``::
 
         >>> from webob import Request
         >>> request = Request.blank('/')
@@ -93,7 +139,7 @@ class Link(Action):
 
 class ListItem(Action):
     """
-    An action rendered as a link::
+    An action rendered as a link contained by a list item::
 
         >>> from webob import Request
         >>> request = Request.blank('/')
@@ -114,6 +160,9 @@ class Input(Action):
         >>> request = Request.blank('/')
         >>> action = Input('myaction',
         ...                value=_('Click here'))
+
+    Rendering::
+
         >>> action.render(request)
         u'<input type="submit" id="myaction" value="Myaction" />'
 
@@ -139,6 +188,8 @@ class UIButton(Action):
           Click here
         </a>
         
+    You can use javascript::
+
         >>> action = UIButton('myaction', icon='ui-icon-trash',
         ...                 content=_("Click here"), attrs={'onclick':'$(#link).click();'})
         >>> print action.render(request)
@@ -164,12 +215,15 @@ class UIButton(Action):
                 self.attrs['href'] = repr('#')
 
 class Actions(list):
-    """
+    """A action list::
+
         >>> actions = Actions('pyramid_formalchemy.actions.delete',
         ...                   Link('link1', content=_('A link'), attrs={'href':'request.application_url'}))
         >>> actions
         [<UIButton delete>, <Link link1>]
 
+    You must use a request to render them::
+
         >>> from webob import Request
         >>> request = Request.blank('/')
         >>> print actions.render(request) #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
@@ -189,10 +243,14 @@ class Actions(list):
         return u'\n'.join([a.render(request, **kwargs) for a in self])
 
 class Languages(Actions):
-    """
+    """Languages actions::
+
         >>> langs = Languages('fr', 'en')
         >>> langs
         [<ListItem fr>, <ListItem en>]
+
+    It take care about the active language::
+
         >>> from webob import Request
         >>> request = Request.blank('/')
         >>> request.cookies['_LOCALE_'] = 'fr'
diff --git a/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.mo b/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.mo
index e30251f..6dcd2de 100644
Binary files a/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.mo and b/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.mo differ
diff --git a/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.po b/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.po
index 987aa6d..e831c89 100644
--- a/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.po
+++ b/pyramid_formalchemy/locale/fr/LC_MESSAGES/pyramid_formalchemy.po
@@ -9,7 +9,7 @@ msgstr ""
 "Project-Id-Version: pyramid_formalchemy 0.3\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
 "POT-Creation-Date: 2011-06-18 12:02+0200\n"
-"PO-Revision-Date: 2011-06-18 13:18+0200\n"
+"PO-Revision-Date: 2011-06-18 19:54+0200\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: fr <LL@li.org>\n"
 "Plural-Forms: nplurals=2; plural=(n > 1)\n"
@@ -18,39 +18,39 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Generated-By: Babel 0.9.5\n"
 
-#: pyramid_formalchemy/actions.py:190
+#: pyramid_formalchemy/actions.py:206
+msgid "French"
+msgstr "Français"
+
+#: pyramid_formalchemy/actions.py:207
+msgid "English"
+msgstr "Anglais"
+
+#: pyramid_formalchemy/actions.py:224
 msgid "New ${model_name}"
 msgstr "Nouveau ${model_name}"
 
-#: pyramid_formalchemy/actions.py:198
+#: pyramid_formalchemy/actions.py:232
 msgid "Save"
 msgstr "Sauver"
 
-#: pyramid_formalchemy/actions.py:205
+#: pyramid_formalchemy/actions.py:239
 msgid "Save and add another"
 msgstr "Sauver et ajouter un autre"
 
-#: pyramid_formalchemy/actions.py:214
+#: pyramid_formalchemy/actions.py:248
 msgid "Edit"
 msgstr "Editer"
 
-#: pyramid_formalchemy/actions.py:221
+#: pyramid_formalchemy/actions.py:255
 msgid "Back"
 msgstr "Retour"
 
-#: pyramid_formalchemy/actions.py:229
+#: pyramid_formalchemy/actions.py:263
 msgid "Delete"
 msgstr "Supprimer"
 
-#: pyramid_formalchemy/actions.py:240
+#: pyramid_formalchemy/actions.py:274
 msgid "Cancel"
 msgstr "Annuler"
 
-#: pyramid_formalchemy/views.py:245
-msgid "edit"
-msgstr "Editer"
-
-#: pyramid_formalchemy/views.py:252
-msgid "delete"
-msgstr "Supprimer"
-
diff --git a/pyramid_formalchemy/locale/pyramid_formalchemy.pot b/pyramid_formalchemy/locale/pyramid_formalchemy.pot
index 1278b5c..726b3a2 100644
--- a/pyramid_formalchemy/locale/pyramid_formalchemy.pot
+++ b/pyramid_formalchemy/locale/pyramid_formalchemy.pot
@@ -9,7 +9,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: pyramid_formalchemy 0.3\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2011-06-18 13:16+0200\n"
+"POT-Creation-Date: 2011-06-18 19:54+0200\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -18,39 +18,39 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Generated-By: Babel 0.9.5\n"
 
-#: pyramid_formalchemy/actions.py:190
+#: pyramid_formalchemy/actions.py:206
+msgid "French"
+msgstr ""
+
+#: pyramid_formalchemy/actions.py:207
+msgid "English"
+msgstr ""
+
+#: pyramid_formalchemy/actions.py:224
 msgid "New ${model_name}"
 msgstr ""
 
-#: pyramid_formalchemy/actions.py:198
+#: pyramid_formalchemy/actions.py:232
 msgid "Save"
 msgstr ""
 
-#: pyramid_formalchemy/actions.py:205
+#: pyramid_formalchemy/actions.py:239
 msgid "Save and add another"
 msgstr ""
 
-#: pyramid_formalchemy/actions.py:214
+#: pyramid_formalchemy/actions.py:248
 msgid "Edit"
 msgstr ""
 
-#: pyramid_formalchemy/actions.py:221
+#: pyramid_formalchemy/actions.py:255
 msgid "Back"
 msgstr ""
 
-#: pyramid_formalchemy/actions.py:229
+#: pyramid_formalchemy/actions.py:263
 msgid "Delete"
 msgstr ""
 
-#: pyramid_formalchemy/actions.py:240
+#: pyramid_formalchemy/actions.py:274
 msgid "Cancel"
 msgstr ""
 
-#: pyramid_formalchemy/views.py:245
-msgid "edit"
-msgstr ""
-
-#: pyramid_formalchemy/views.py:252
-msgid "delete"
-msgstr ""
-
diff --git a/pyramid_formalchemy/views.py b/pyramid_formalchemy/views.py
index 2a1b652..f297fff 100644
--- a/pyramid_formalchemy/views.py
+++ b/pyramid_formalchemy/views.py
@@ -39,6 +39,7 @@ class Session(object):
         """commit transaction"""
 
 def set_language(request):
+    """Set the _LOCALE_ cookie used by ``pyramid``"""
     resp = exc.HTTPFound(location=request.referer or request.application_url)
     resp.set_cookie('_LOCALE_', request.GET.get('_LOCALE_', 'en'))
     return resp