--- a/doc/book/en/B050-data-as-objects.en.txt	Mon Nov 24 10:22:04 2008 -0800
+++ b/doc/book/en/B050-data-as-objects.en.txt	Mon Nov 24 13:59:09 2008 -0800
@@ -1,142 +1,144 @@
 .. -*- coding: utf-8 -*-
 
 
-Manipulation des données stockées
-=================================
+Stored data handling
+====================
 
-Les classes `Entity` et `AnyEntity`
------------------------------------
-Pour fournir un comportement spécifique à un type d'entité, il suffit de définir
-une classe héritant de la class `ginco.entities.AnyEntity`. En général il faut
-définir ces classes dans un module du package `entities` d'une application pour 
-qu'elle soit disponible à la fois coté serveur et coté client.
+Classes `Entity` and `AnyEntity`
+--------------------------------
 
-La classe `AnyEntity` est une classe chargée dynamiquement héritant de la classe
-de base `Entity` (`ginco.common.entity`). On définit une sous-classe pour
-ajouter des méthodes ou spécialiser les comportements d'un type d'entité donné.
+To provide a specific behavior for each entity, we just need to define
+a class inheriting from `cubicweb.entities.EnyEntity`. In genera, we have
+to defined those classes in a module of `entites` package of an application
+so that it will be available on both server and client side.
 
-Des descripteurs sont ajoutés à l'enregistrement pour initialiser la classe en
-fonction du schéma :
+The class `AnyEntity` is loaded dynamically from the class `Entity` 
+(`cubciweb.common.entity`). We define a sub-class to add methods or to
+specialize the handling of a given entity type
 
-* on peut accéder aux attributs définis dans le schéma via les attributs de même
-  nom sur les instances (valeur typée)
+Descriptors are added when classes are registered in order to initialize the class
+according to its schema:
+
+* we can access the defined attributes in the schema thanks the attributes of
+  the same name on instances (typed value)
 
-* on peut accéder aux relations définies dans le schéma via les attributs de même
-  nom sur les instances (liste d'instances d'entité)
+* we can access the defined relations in the schema thanks to the relations of
+  the same name on instances (entities instances list)
 
-Les méthodes définies sur la classe `AnyEntity` ou `Entity` sont les suivantes :
+The methods defined for `AnyEntity` or `Entity` are the following ones:
 
-* `has_eid()`, retourne vrai si l'entité à un eid affecté (i.e. pas en cours de
-  création) 
+* `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the
+  creation process)
         
-* `check_perm(action)`, vérifie que l'utilisateur à le droit d'effectuer
-  l'action demandée sur l'entité
+* `check_perm(action)`, checks if the user has the permission to execcute the
+  requested action on the entity
 
-:Formattage et génération de la sortie:
+:Formatting and output generation:
 
-  * `view(vid, **kwargs)`, applique la vue donnée à l'entité
+  * `view(vid, **kwargs)`, apply the given view to the entity
 
-  * `absolute_url(**kwargs)`, retourne une URL absolue permettant d'accéder à la
-    vue primaire d'une entité
+  * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view
+    of an entity
+    
+  * `rest_path()`, returns a relative REST URL to get the entity
 
-  * `rest_path()`, renvoie une l'URL REST relative permettant d'obtenir l'entité
-
-  * `format(attr)`, retourne le format (type MIME) du champ passé en argument
+  * `format(attr)`, returns the format (MIME type) of the field given un parameter
 
   * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 
-    retourne une chaine permettant l'affichage dans un format donné de la valeur
-    d'un attribut (la valeur est automatiquement récupérée au besoin)
+    returns a string enabling the display of an attribute value in a given format
+    (the value is automatically recovered if necessarry)
 
-  * `display_name(form='')`, retourne une chaîne pour afficher le type de
-    l'entité, en spécifiant éventuellement la forme désirée ('plural' pour la
-    forme plurielle)
+  * `display_name(form='')`, returns a string to display the entity type by 
+    specifying the preferred form (`plural` for a plural form)
 
-:Gestion de données:
+:Data handling:
 
-  * `as_rset()`, transforme l'entité en un resultset équivalent simulant
-     le résultat de la requête `Any X WHERE X eid _eid_`
+  * `as_rset()`, converts the entity into an equivalent result set simulating the 
+     request `Any X WHERE X eid _eid_`
 
-  * `complete(skip_bytes=True)`, effectue une requête permettant de récupérer d'un
-    coup toutes les valeurs d'attributs manquant sur l'entité
+  * `complete(skip_bytes=True)`, executes a request that recovers in one time
+    all the missing attributes of an entity
 
-  * `get_value(name)`, récupere la valeur associée à l'attribut passé en argument
+  * `get_value(name)`, returns the value associated to the attribute name given
+    in parameter
 
-  * `related(rtype, x='subject', limit=None, entities=False)`, retourne une liste
-    des entités liées à l'entité courant par la relation donnée en argument
-
-  * `unrelated(rtype, targettype, x='subject', limit=None)`, retourne un result set
-    des entités not liées à l'entité courante par la relation donnée en argument
-    et satisfaisants les contraintes de celle-ci
+  * `related(rtype, x='subject', limit=None, entities=False)`, returns a list
+    of entities related to the current entity by the relation given in parameter
 
-  * `set_attributes(**kwargs)`, met à jour la liste des attributs avec
-    les valeurs correspondantes passées sous forme d'arguments nommés
+  * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set
+    corresponding to the entities not related to the current entity by the
+    relation given in parameter and satisfying its constraints
 
-  * `copy_relations(ceid)`, copie les relations de l'entité ayant l'eid passé en
-    argument sur l'entité courante
+  * `set_attributes(**kwargs)`, updates the attributes list with the corresponding
+    values given named parameters
 
-  * `last_modified(view)`, retourne la date à laquelle on doit considérer
-    l'objet comme modifié (utiliser par la gestion de cache HTTP)
+  * `copy_relations(ceid)`, copies the relations of the entities having the eid
+    given in the parameters on the current entity
+
+  * `last_modified(view)`, returns the date the object has been modified
+    (used by HTTP cache handling)
 
-  * `delete()` permet de supprimer l'entité représentée
+  * `delete()` allows to delete the entity
   
-:Meta-données standard (Dublin Core):
+:Standard meta-data (Dublin Core):
 
-  * `dc_title()`, retourne une chaine unicode correspondant à la méta-donnée
-    'Title' (utilise par défaut le premier attribut non 'meta' du schéma de
-    l'entité) 
+  * `dc_title()`, returns a unicode string corresponding to the meta-data
+    `Title` (used by default the first attribute non-meta of the entity
+    schema)
 
-  * `dc_long_title()`, comme dc_title mais peut retourner un titre plus détaillé
+  * `dc_long_title()`, same as dc_title but can return a more
+    detailled title
 
-  * `dc_description(format='text/plain')`, retourne une chaine unicode
-     correspondant à la méta-donnée 'Description' (cherche un attribut
-     'description' par défaut)
+  * `dc_description(format='text/plain')`, returns a unicode string 
+    corresponding to the meta-data `Description` (look for a description
+    attribute by default)
 
-  * `dc_authors()`, retourne une chaine unicode correspondant à la méta-donnée
-    'Authors' (propriétaires par défaut)
+  * `dc_authors()`, returns a unicode string corresponding to the meta-data 
+    `Authors` (owners by default)
 
-  * `dc_date(date_format=None)`, retourne une chaine unicode
-     correspondant à la méta-donnée 'Date' (date de modification par défaut)
+  * `dc_date(date_format=None)`, returns a unicode string corresponding to 
+    the meta-data `Date` (update date by default)
             
-:Contrôle du vocabulaire pour les relations:
+:Vocabulary control on relations:
 
-  * `vocabulary(rtype, x='subject', limit=None)`, appelée notamment
-    par les vues d'édition d'erudi, elle renvoie une liste de couple
-    (label, eid) des entités qui pourraient être liées à l'entité
-    via la relation `rtype`
-  * `subject_relation_vocabulary(rtype, limit=None)`, appelée
-    en interne par `vocabulary` dans le cas d'une relation sujet
-  * `object_relation_vocabulary(rtype, limit=None)`, appelée
-    en interne par `vocabulary` dans le cas d'une relation objet
-  * `relation_vocabulary(rtype, targettype, x, limit=None)`, appelé
-    en interne par `subject_relation_vocabulary` et `object_relation_vocabulary`
+  * `vocabulary(rtype, x='subject', limit=None)`, called by the
+    editing views, it returns a list of couples (label, eid) of entities
+    that could be related to the entity by the relation `rtype`
+  * `subject_relation_vocabulary(rtype, limit=None)`, called internally 
+    by  `vocabulary` in the case of a subject relation
+  * `object_relation_vocabulary(rtype, limit=None)`, called internally 
+    by  `vocabulary` in the case of an object relation
+  * `relation_vocabulary(rtype, targettype, x, limit=None)`, called
+    internally by `subject_relation_vocabulary` and `object_relation_vocabulary`
 
 
-Les *rtags*
------------
-Les *rtags* permettent de spécifier certains comportements propres aux relations
-d'un type d'entité donné (voir plus loin). Ils sont définis sur la classe 
-d'entité via l'attribut `rtags` qui est un dictionnaire dont les clés sont un 
-triplet ::
+*rtags*
+-------
 
-  <type de relation>, <type d'entité cible>, <position du contexte ("subject" ou "object"
+*rtags* allows to specify certain behaviors of relations relative to a given
+entity type (see later). They are defined on the entity class by the attribute
+`rtags` which is a dictionnary with as its keys the triplet ::
 
-et les valeurs un `set` ou un tuple de marqueurs définissant des propriétés 
-s'appliquant à cette relation. 
+  <relation type>, <target entity type>, <context position ("subject" ou "object")>
 
-Il est possible de simplifier ce dictionnaire :
+and as the values a `set` or a tuple of markers defining the properties that
+apply to this relation.
+
+It is possible to simplify this dictionnary:
 
-* si l'on veut spécifier un seul marqueur, il n'est pas nécessaire d'utiliser
-  un tuple comme valeur, le marqueur seul (chaine de caractères) suffit
-* si l'on s'intéresse uniquement à un type de relation et non à la cible et à la
-  position du contexte (ou que celui-ci n'est pas ambigüe), on peut simplement
-  utiliser le nom du type de relation comme clé
-* si l'on veut qu'un marqueur s'applique quelque soit le type d'entité cible, il
-  faut utiliser la chaine `*` comme type d'entité cible
-
-A noter également que ce dictionnaire est *traité à la création de la classe*. 
-Il est automatiquement fusionné avec celui de la ou des classe(s) parentes (pas
-besoin de copier celui de la classe parent pour le modifier). De même modifier
-celui-ci après création de la classe n'aura aucun effet...
+* if we want to specifiy a single marker, it is not necessarry to
+  use a tuple as the value, the marker by itself (characters string)
+  is enough
+* if we only care about a single type of relation and not about the target
+  and the context position (or when this one is not ambigous), we can simply
+  use the name of the relation type as the key
+* if we want a marker to apply independently from the target entity type,
+  we have to use the string `*` as the target entity type
 
 
+Please note that this dictionnary is *treated at the time the class is created*.
+It is automatically merged with the parent class(es) (no need to copy the
+dictionnary from the parent class to modify it). Also, modify it after the 
+class is created will not have any effect...
+
 .. include:: B051-define-entities.en.txt

--- a/doc/book/en/B051-define-entities.en.txt	Mon Nov 24 10:22:04 2008 -0800
+++ b/doc/book/en/B051-define-entities.en.txt	Mon Nov 24 13:59:09 2008 -0800
@@ -1,43 +1,45 @@
 .. -*- coding: utf-8 -*-
 
-Paramétrages et extensions spécifiques
---------------------------------------
+Parametrization and specific extensions
+---------------------------------------
 
-Valeurs par défaut dynamiques
-`````````````````````````````
-Il est possible de définir dans le schéma des valeurs par défaut *statiques*.
-Il est également possible de définir des valeurs par défaut *dynamiques* en 
-définissant sur la classe d'entité une méthode `default_<nom attribut>` pour
-un attribut donnée.
+Dynamic default values
+``````````````````````
+It is possible to define in the schema *static* default values.
+It is also possible to define in the schema *dynamic* default values
+by defining in the entity class a method `default_<attribut name>` for
+a given attribute.
 
 
-Contrôle des attributs chargés et du tri par défaut
-```````````````````````````````````````````````````
-* l'attribut de classe `fetch_attrs` permet de définir sur une classe d'entité
-  la liste des noms des attributs ou relations devant être chargés 
-  automatiquement lors de la récupération d'entité(s) de ce type. Dans le cas 
-  des relations, on est limité aux relations *sujets de cardinalité `?` ou `1`*.
+Control of loaded attributes and default sorting
+````````````````````````````````````````````````
 
-* la méthode de classe `fetch_order(attr, var)` prend en argument un nom 
-  d'attribut (ou de relation) et un nom de variable et doit retourner une chaine
-  à utiliser dans la close "ORDERBY" d'une requête RQL pour trier 
-  automatiquement les listes d'entités de ce type selon cet attribut, ou `None`
-  si l'on ne veut pas de tri sur l'attribut passé en argument. Par défaut les 
-  entités sont triées selon leur date de création
+* The class attribute `fetch_attrs` allows to defined in an entity class
+  a list of names of attributes or relations that should be automatically
+  loaded when we recover the entities of this type. In the case of relations,
+  we are limited to *subject of cardinality `?` or `1`* relations.
+
+* The class method `fetch_order(attr, var)` expects an attribute (or relation)
+  name as a parameter and a variable name, and it should return a string
+  to use in the requirement `ORDER BY` of an RQL query to automatically
+  sort the list of entities of such type according to this attribute, or
+  `None` if we do not want to sort on the attribute given in the parameter.
+  By default, the entities are sorted according to their creation date.
 
-* la méthode de classe `fetch_unrelated_order(attr, var)` est similaire à la 
-  méthode `fetch_order` mais est utilisée essentiellement pour contrôler le tri
-  des listes déroulantes permettant de créer des relations dans la vue d'édition
-  d'une entité
+* The class method `fetch_unrelated_order(attr, var)` is similar to the 
+  method `fetch_order` except that it is essentially used to control
+  the sorting of drop-down lists enabling relations creation in 
+  the editing view of an entity.
 
-La fonction `fetch_config(fetchattrs, mainattr=None)` permet de simplifier la 
-définition des attributs à précharger et du tri en retournant une liste des 
-attributs à précharger (en considérant ceux de la classe  `AnyEntity`
-automatiquement) et une fonction de tri sur l'attribut "principal" (le 2eme 
-argument si spécifié ou sinon le premier attribut de la liste `fetchattrs`).
-Cette fonction est définie dans le package `ginco.entities`.
+The function `fetch_config(fetchattrs, mainattr=None)` simplifies the
+definition of the attributes to load and the sorting by returning a 
+list of attributes to pre-load (considering automatically the attributes
+of `AnyEntity`) and a sorting function based on the main attribute
+(the second parameter if specified otherwisethe first attribute from
+the list `fetchattrs`).
+This function is defined in `cubicweb.entities`.
 
-Par exemple : ::
+By example: ::
 
   class Transition(AnyEntity):
     """..."""