Rails-spec.md

-# Ecriture de fichier spec
+# Guidelines for writing a spec file
 
-## Spec de `Model`
-## Spec de `View`
+## Model spec
+## View spec
 
 ### Helpers
 
-- _matcher_ `have_link_for_each_item`  qui permet d'itérer sur tous les éléments d'une collection, et de vérifier - pour chacun - qu'on a un lien vers l'URL désirée (dans [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22)).
-- _matcher_ `have_the_right_number_of_links`  qui permet d'itérer sur tous les éléments d'une collection, et de vérifier - pour chacun - qu'on a le bon nombre de liens (dans [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22)).
-- `with_permission permission_name do ...` qui permet de tester le rendu avec un utilisateur disposant de la permission désirée (dans [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22)).
-- `build_paginated_collection(:factory_name, decorator_class, factory_options, context: decorator_context)` permet de construire une collection d'objets et de les décorer, de façon similaire à ce que ferait un controlleur (dans [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22).
+- _matcher_ `have_link_for_each_item` checks that each item in the given collection has a link to the expected URL (defined in [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22)).
+- _matcher_ `have_the_right_number_of_links` checks that each item in the given collection has the expected number of links (defined in [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22)).
+- `with_permission PERMISSION_NAME do ...` a context manager that enables view testing with the given permission activated (defined in [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22)).
+- `build_paginated_collection(:factory_name, decorator_class, factory_options, context: decorator_context)` creates a collection of decorated objects using factories, with a result similar to what would be created in the controller (defined in [`spec/support/integration_spec_helper.rb`](http://github.com/af83/stif-boiv/blob/f83df1a0b39b2af7d3088db9c98365c4088bc021/spec/support/integration_spec_helper.rb#L22)).
 
 ### Tips
 
-- pour _nester_ la vue, par exemple émuler une URL `/parents/:parent_id/objects`: `controller.request.path_parameters[:parent_id] = parent.id`
+- to simulate a nested route (for example, `/parents/:parent_id/objects`):
 
-### Exemple
+        controller.request.path_parameters[:parent_id] = parent.id
 
-Pour une vue d'__index__, dans laquelle on veut vérifier:
-- le nombre de lignes du tableau
-- la présence de lien pour chaque ligne (en fonction des permissions)
+### Example
+
+Here's an example `index` view spec, where we want to verify:
+
+- the number of rows in the table
+- that each row has a link (accounting for permissions)
 
 ```ruby
 require 'spec_helper'
@@ -59,14 +62,14 @@ describe "/objects/index", :type => :view do
 end
 ```
 
-## Spec de `Controller`
+## Controller spec
 
 ### Helpers
 
-- `login_user` pour créer un utilisateur et le passer dans la session
-- `with_permission permission do ...` pour ajouter la permission à l'utilisateur connecté dans le contexte
+- `login_user` to create a `User` and authenticate it in the session
+- `with_permission PERMISSION do ...` to add the given permission to the current user in the context of the block
 
-### Exemple
+### Example
 
 ```ruby
 RSpec.describe ObjectController, :type => :controller do