diff --git a/rails-i18n.md b/rails-i18n.md
index e9ed1215d..ececf1b28 100644
--- a/rails-i18n.md
+++ b/rails-i18n.md
@@ -5,73 +5,250 @@ layout: default
 
 ### Basics
 
-    t('my.messages.hello')
+```rb
+t('my.messages.hello')
 
-    t(:hello, scope: 'my.messages')
-    t(:hello, scope: [:my, :messages])
+# same as 'my.messages.hello'
+t(:hello, scope: 'my.messages')
+t(:hello, scope: [:my, :messages])
 
-    t('my.messages.hello', default: "Hello")
+t('my.messages.hello', default: "Hello")
+```
+
+### Interpolation
+
+```rb
+t('hello', name: "John")
+```
+
+```yml
+hello: "Hello %{name}"
+```
+
+### Lazy lookup
+
+```yml
+en:
+  books:
+    index:
+      title: "Título"
+```
+
+```rb
+# from the 'books/index' view
+t('.title')
+```
 
 ### Plural
 
-    I18n.backend.store_translations :en, inbox: {
-        one: 'one message',
-        other: '%{count} messages'
-    }
-    I18n.translate :inbox, count: 1  # => 'one message'
-    I18n.translate :inbox, count: 2  # => '2 messages'
+```rb
+t(:inbox, count: 1)  #=> 'one message'
+t(:inbox, count: 2)  #=> '2 messages'
+```
+
+```yml
+inbox:
+  one: 'one message',
+  other: '%{count} messages'
+```
+
+## Localizing
 
 ### Time
 
-    en:
-      date:
-        formats:
-          default: "%Y-%m-%d"
-          short: "%b %d"
-      time:
-        formats:
-          default: "%a, %d %b %Y %H:%M:%S %z"
-          short: "%d %b %H:%M"
+```rb
+l(Time.now)
+l(Time.now, format: :short)
+```
 
-    I18n.l Time.now
-    I18n.l Time.now, format: :short
+```yml
+en:
+  time:
+    formats:
+      default: "%a, %d %b %Y %H:%M:%S %z"
+      short: "%d %b %H:%M"
+```
 
-### ActiveRecord
+### Date
 
-    activerecord:
-      attributes:
-        user:
-          name: "Name"
-      errors:
-        models:
-          venue:
-            attributes:
-              name:
-                blank: "Please enter a name."
+```rb
+l(Date.today)
+```
 
-    t 'blank', scope:
-      activerecord.errors.models.[model_name].attributes.[attribute_name]
-      activerecord.errors.models.[model_name]
-      activerecord.errors.messages
-      errors.attributes.[attribute_name]
-      errors.messages
+```yml
+en:
+  date:
+    formats:
+      default: "%Y-%m-%d"
+      short: "%b %d"
+```
 
-    helpers.submit.[model]:
-      create: "Create a %{model}"
-      update: "Update %{model}"
+## ActiveRecord
 
-    confirmation - :confirmation
-    acceptance   - :accepted
-    presence     - :blank
-    length       - :too_short (%{count})
-    length       - :too_long (%{count})
-    length       - :wrong_length (%{count})
-    uniqueness   - :taken
-    format       - :invalid
-    numericality - :not_a_number
+### Attributes
 
-    activerecord.errors.template.header:
-      one: "1 error prohibited this %{model} from being saved"
+```rb
+User.model_name.human            #=> "User"
+Child.model_name.human(count: 2) #=> "Children"
+User.human_attribute_for :name   #=> "Name"
+```
+
+```yml
+en:
+  activerecord:
+    models:
+      user: "User"
+      child:
+        one: "Child"
+        other: "Children"
+    attributes:
+      user:
+        # activerecord.attributes.<model>.<field>
+        name: "Name"
+        email: "Email"
+```
+
+### Errors
+
+```yml
+activerecord:
+  errors:
+    models:
+      venue:
+        attributes:
+          name:
+            blank: "Please enter a name."
+```
+
+Possible scopes (in order):
+
+```yml
+activerecord.errors.models.[model_name].attributes.[attribute_name].[error]
+activerecord.errors.models.[model_name].[error]
+activerecord.errors.messages.[error]
+errors.attributes.[attribute_name].[error]
+errors.messages.[error]
+```
+
+Where `[error]` can be:
+
+```yml
+validates
+  confirmation - :confirmation
+  acceptance   - :accepted
+  presence     - :blank
+  length       - :too_short (%{count})
+  length       - :too_long (%{count})
+  length       - :wrong_length (%{count})
+  uniqueness   - :taken
+  format       - :invalid
+  numericality - :not_a_number
+```
+
+```rb
+error_messages_for(...)
+```
+
+### Labels
+
+```
+helpers:
+  # helpers.label.<model>.<field>
+  label:
+    post:
+      body: "Your body text"
+```
+
+### Submit
+
+```yml
+helpers:
+  submit:
+    # helpers.submit.<action>
+    create: "Create a %{model}"
+    update: "Confirm changes to %{model}"
+
+    # helpers.submit.<model>.<action>
+    article:
+      create: "Publish article"
+      update: "Update article"
+```
  
-### Reference
+
+## Numbers
+
+```rb
+number_to_delimited(2000)             #=> "2,000"
+number_to_currency(12.3)              #=> "$12.30"
+number_to_percentage(0.3)             #=> "30%"
+number_to_rounded(3.14, precision: 0) #=> "3"
+number_to_human(12_000)               #=> "12 Thousand"
+number_to_human_size(12345)           #=> "12.3 kb"
+```
+
+### Delimited
+
+```rb
+number_to_delimited(n)
+```
+
+```yml
+number:
+  format:
+    separator: '.'
+    delimiter: ','
+    precision: 3
+    significant: false
+    strip_insignificant_zeroes: false
+```
+
+### Currencies
+
+```rb
+number_to_currency(n)
+```
+
+```yml
+number:
+  currency:
+    format:
+      format: "%u%n" # %u = unit, %n = number
+      unit: "$"
+      separator: '.'
+      delimiter: ','
+      precision: 3
+      # (see number.format)
+```
+
+### Percentage
+
+```rb
+number_to_percentage(n)
+```
+
+```yml
+number:
+  percentage:
+    format:
+      format: "%n%"
+      # (see number.format)
+```
+
+## Programmatic access
+
+```rb
+I18n.backend.store_translations :en, ok: "Ok"
+I18n.locale = :en
+I18n.default_locale = :en
+
+I18n.available_locales
+
+I18n.translate :ok   # aka, I18n.t
+I18n.localize date   # aka, I18n.l
+```
+
+## Reference
+
  * http://guides.rubyonrails.org/i18n.html
+ * http://rails-i18n.org/wiki
+ * https://github.com/svenfuchs/i18n