--- a/doc/book/en/12-internationalization.en.txt	Fri Nov 14 19:02:07 2008 +0100
+++ b/doc/book/en/12-internationalization.en.txt	Mon Nov 17 17:13:25 2008 +0100
@@ -6,68 +6,95 @@
 Internationalization
 ====================
 
-The internationalization 
+Cubicweb fully supports the internalization of it's content and interface.
 
-Le système d'internationalisation de l'interface web d'erudi est basé sur le
-système `GNU gettext`_.
+Cubicweb's interface internationalization is based on the translation project `GNU gettext`_.
 
 .. _`GNU gettext`: http://www.gnu.org/software/gettext/
 
-Messages à internationaliser
-----------------------------
+Cubicweb' internalization involves two steps:
+
+* in your Python code and cubicweb-tal templates : mark translatable strings
+
+* in your application : handle the translation catalog
+ 
+String internalization
+----------------------
 
-Marquage des messages à internaliser
-````````````````````````````````````
-Les chaines de caractères à internationaliser sont marqués par l'appel à la
-fonction `_` *OU* par la méthode équivalent de la requête dans le code python ou
-dans les expressions python de template TAL. 
+In the Python code and cubicweb-tal templates translatable strings can be
+marked in one of the following ways :
+
+ * by using the *built-in* function `_` ::
+
+   class PrimaryView(EntityView):
+       """the full view of an non final entity"""
+       id = 'primary'
+       title = _('primary')
+
+  OR
 
-Dans les templates erudi-tal, il est également possible d'insérer une chaine à
-traduire via les balises `i18n:content` et  `i18n:replace`.
-
-De plus des messages correspondant aux entités/relations utilisés par le schéma
-de l'application seront automatiquement ajoutés.
+ * by using the equivalent request's method ::
+   
+   class NoResultView(EmptyRsetView):
+       """default view when no result has been found"""
+       id = 'noresult'
+    
+       def call(self, **kwargs):
+           self.w(u'<div class="searchMessage"><strong>%s</strong></div>\n'
+               % self.req._('No result matching query'))
 
-Renvoi d'un message internationalisé lors de la construction d'une page
-```````````````````````````````````````````````````````````````````````
-La fonction *built-in* `_` ne doit servir qu'**à marquer les messages à
-traduire**, non pas à récupérer une traduction. Il faut pour cela utiliser la
-méthode `_` de l'objet requête, sans quoi vous récupérerez l'identifiant de
-message au lieu de sa traduction dans la langue propre à la requête.1
+The goal of the *built-in* function `_` is only **to mark the
+translatable strings**, it will only return the translation string
+it-self, but not it's translation.
+
+In the other hand the request's method `_` is ment to retrive the
+proper translation of translation strings in the requested language.
+
+Translations in cubicweb-tal template can also be done with TAL tags
+`i18n:content` and `i18n:replace`.
+
+Note ::
+
+   We dont need to mark the translation strings of entities/relations
+   used by a particular application's schema as they are generated
+   automatically.
 
 
-Gestion des catalogues de traduction
-------------------------------------
-Une fois l'application rendu internationalisable coté code, reste à gérer les
-catalogues de traductions. erudi-ctl intègre pour cela les commandes suivantes : 
-
-* `i18nlibupdate`, met à jour les catalogues de messages *de la librairie
-  erudi*. Sauf si vous développez sur le framework (et non votre propre
-  application), vous ne devriez pas avoir à utiliser cette commande
+Handle the translation catalog 
+------------------------------
 
-* `i18nupdate`, met à jour les catalogues de messages *du composant* (ou de tous
-  les composants). A la suite de cette commande, vous devez mettre à jour les
-  fichiers de traduction *.po* dans le sous-répertoire "i18n" de votre
-  template. Évidemment les traductions précédentes toujours utilisées ont été
-  conservées.
-
-* `i18ncompile`, recompile les catalogues de messages *d'une instance* (ou de
-  toutes les instances) après mise à jour des catalogues de son composant. Cela
-  est effectué automatiquement lors d'une création ou d'une mise à jour. Les
-  catalogues de messages compilés se trouvent dans le répertoire
-  "i18n/<lang>/LC_MESSAGES/erudi.mo" de l'application où `lang` est
-  l'identifiant de la langue sur 2 lettres ('en' ou 'fr' par exemple)
+Once the internalization is done in your application's code, you need
+to populate and update the translation catalog. Cubicweb provides the
+following commands for this purpose:
 
 
-Le cas classique
-````````````````
-Vous avez ajouté et/ou modifié des messages d'un composant utilisé par votre
-application (en ajoutant une nouvelle vue ou en ayant modifié le schéma par
-exemple) :
+* `i18nlibupdate` updates Cubicweb framework's translation
+  catalogs. Unless you work on the framework development, you dont
+  need to use this command.
+
+* `i18nupdate` updates the translation catalogs of *one particular
+  component* (or of all components). FIXME After this command is
+  executed you must update the translation files *.po* in the "i18n"
+  directory of your template. This command will of course not remove
+  existing translations still in use
 
-1. `cubicweb-ctl i18nupdate <composant>`
-2. éditer les fichiers <composant>/xxx.po dans pour y rajouter les traductions
-   manquantes (`msgstr` vide) 
+* `i18ncompile` recompile the transaltion catalogs of *one particular
+  instance* (or of all instances) after the translation catalogs of
+  its components have been updated. This command is automatically
+  called every time you create or update your instance. The compiled
+  catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of
+  application where `lang` is the language identifier ('en' or 'fr'
+  for exemple).
+
+
+Example 
+```````
+You have added and/or modified some translation strings in your application
+(after creating a new view or modifying the application's schema for exemple). 
+To update the translation catalogs you need to do:
+ 
+1. `cubicweb-ctl i18nupdate <component>`
+2. Edit the <component>/xxx.po  files and add missing translations (empty `msgstr`) 
 3. `hg ci -m "updated i18n catalogs"`
-4. `cubicweb-ctl i18n compile <monapplication>`
+4. `cubicweb-ctl i18n compile <myapplication>`