Also improve some of the code sample sections, using the correct names
for things, being more specific about where things go, and using more
whitespace to improve readability.

Rails-views.md

-## Decorateurs
+## Decorators
 
 ### Usage
 
-On ne définit qu'un seul décorateur, qui hérite de la classe `AF83::Decorator`.
-Il est responsable de décorer les collections ainsi que les instances.
-Dans les controlleurs, le code devient donc simplement:
+We define only a single decorator per model that must inherit from `AF83::Decorator`. This model decorator handles both collections and instances. To decorate an `Item` object:
+
 ```ruby
-  # dans l'index
-  @items = ItemDecorator.decorator(@items)
+# app/controllers/items_controller.rb
+def index
+  # ...
+  @items = ItemDecorator.decorate(@items)
+  # ...
+end
 
-  # dans le show
+def show
+  # ...
   @item = @item.decorate
+  # ...
+end
 ```
-Les actions disponibles sur la __collection__ sont définies à la racine du décorateur, 
-alors que celles attachées aux instances sont définies à l'aide du block `with_instance_decorator`.
 
-Pour définir une action, on utilise la méthode `action_link`. Les options disponibles sont:
-- `on`: limite la visibilité du lien aux actions listées (`on: %i(show index)`)
-- `if`: reçoit une `Proc`, et n'affiche le lien que si le résultat est _trueish_
-- `policy`: le lien n'est accessible que si l'utilisateur courant dispose du droit correspondant sur l'objet décoré (on ne passe que le nom de la permission : `edit`, `create`, etc.)
-- `feature`: comme pour `policy`, mais avec une `feature`
-- `weight`: pour modifier l'ordre d'affichage des liens (par défaut l'ordre de déclaration est utilisé)
+The actions on the **collection** are defined at the root of the decorator, while those for instances are defined with the help of a `with_instance_decorator` block.
+
+To define an action, we use the `action_link` method. The method accepts these options:
 
-Les actions sont aussi réparties dans des __groupes__. Il y a plusieurs syntaxes possibles pour cela:
+- `on`: only shows the link on the pages for the listed actions (e.g. `on: %i(show index)`)
+- `if`: takes a `Proc` and only displays the link if the proc result is _truthy_
+- `policy`: only shows the link if the current user has the permission for the decorated object and action link (takes an action argument, for example `:edit`, or `:create`)
+- `feature`: like `policy`, but for a `feature`
+- `weight`: allow the links' display order to be changed, with `weight: 1` shown first (by default, the declaration order is used)
+
+Actions are also split into **groups**. These can be customised in several ways:
 ```ruby
-groups: { primary: true, secondary: %i(index show), any_other_group: :index)}
+groups: {
+  primary: true,
+  secondary: %i(index show),
+  any_other_group: :index
+}
 ```
 
-Des raccourcis sont disponibles pour les groupes `primary`, `secondary` et `footer`. 
-On peut dont écrire `action_link primary: :index` plutôt que  `action_link groups: {primary: :index}`
+Shortcuts are available for the `primary`, `secondary`, and `footer` groups. These enable us to write `action_link primary: :index` instead of `action_link groups: { primary: :index }`.
+
+Link content is defined in a block. Each method called on the object passed into the block is converted into an attribute on the resulting HTML tag, except for these:
+
+- `extra_class`: Adds one or more classes to the link. Takes either an `Array` or a `String`.
+- `class`: **Replaces** the link's classes. Takes either an `Array` or a `String`.
+- `type`: Allows the HTML tag to be changed. The only value currently implemented is `:button`. All others fall back on `<a>`.
+
+#### Shortcuts
 
-Le contenu du lien est défini à l'aide d'un bloc (cf exemple).
-Chaque méthode appelée sur l'objet passé au bloc est convertie en attribut sur la balise HTML résultante, 
-à l'exception de certaines méthodes spécifiques:
-- `extra_class`: ajoute une (ou des) classe(s) au lien. Peut recevoir un tableau ou une string. 
-- `class`: __REMPLACE__ les classes du lien. Peut recevoir un tableau ou une string. 
-- `type`: permet de définir le type de balise HTML à utiliser. Seule la valeur `button` est implémentée, les autres _fallback_ sur un `<a>`
+Four methods are available to define _common_ actions:
 
-#### Raccourcis
+- `create_action_link`: adds a `create` link for a collection
+- `show_action_link`: adds a `show` link on an instance
+- `edit_action_link`: adds an `edit` link on an instance
+- `destroy_action_link`: adds a `destroy` link on an instance
 
-4 méthodes sont disponibles pour définir des actions _communes_:
-- `create_action_link`: pour ajouter un lien de création d'un objet sur une collection
-- `show_action_link`: pour ajouter un lien d'affichage d'un objet sur une instance
-- `edit_action_link`: pour ajouter un lien de modification d'un objet sur une instance
-- `destroy_action_link`: pour ajouter un lien de suppression d'un objet sur une instance
+These are defined in the `AF83::Decorator::EnhancedDecorator` module.
 
-Ils sont définis dans la classe `AF83::EnhancedDecorator`.
+### Behavior
 
-### Comportement
+The default behavior is as follows:
 
-Le comportement par défaut est le suivant:
+#### On the `index` page
 
-#### Sur la page `index`
+Actions from the collection's `primary` group are rendered in the main section of the header (and retained in the "sticky" header). Below the main header, actions for the collection's `secondary` group are rendered.
 
-Dans la zone principale du header (qui est reprise dans le header _sticky_), on affiche les actions
-du groupe `primary` de la collection.
-Dans la zone secondaire du header (sous la one principale), on affiche les actions
-du groupe `secondary` de la collection.
-Dans le TableBuilderHelper, on affiche toutes les actions des groupes `primary`, `secondary` et `footer` sur chaque instance,
-groupées par groupe. A noter, le groupe `footer` est systématiquement affiché en dernier.
+In the `TableBuilderHelper`, all actions in the `primary`, `secondary`, and `footer` groups are rendered in a menu next to each instance, separated by group. The `footer` group always comes last.
 
-#### Sur la page `show`
+#### On the `show` page
 
-Dans la zone principale du header (qui est reprise dans le header _sticky_), on affiche les actions
-du groupe `primary` de l'objet.
-Dans la zone secondaire du header (sous la one principale), on affiche les actions
-du groupe `secondary` de l'objet.
+Actions from the object's `primary` group are rendered in the main section of the header (and retained in the "sticky" header). Below the main header, actions for the object's `secondary` group are rendered.
 
 
-### Exemples
+### Examples
 
-#### Decorateur simple
+#### Simple decorator
 
 ```ruby
 class CalendarDecorator < AF83::Decorator
@@ -88,7 +92,7 @@ class CalendarDecorator < AF83::Decorator
 end
 ```
 
-#### Decorateur plus complexe
+#### More complex decorator
 
 ```ruby
 class LineDecorator < AF83::Decorator
@@ -159,5 +163,4 @@ end
 
 ## Breadcrumb
 
-Le fil d'ariane est géré via le gem [Gretel](https://github.com/lassebunk/gretel).
-La configuration se fait via le fichier config/breadcrumbs.rb.
+The breadcrumb is built with the [Gretel](https://github.com/lassebunk/gretel) gem. Its configuration is stored in the `config/breadcrumbs.rb` file.