Adding documentation for ActiveModel::Translation

2 files changed, 26 insertions, 2 deletions

diff --git a/activemodel/README b/activemodel/README
index 7d18571227..6673427230 100644
--- a/activemodel/README
+++ b/activemodel/README
@@ -167,3 +167,12 @@ functionality from the following modules:
 
   {Learn more}[link:classes/ActiveModel/StateMachine.html]
 
+* Integrating with Rail's internationalization (i18n) handling through
+  ActiveModel::Translations...
+
+    class Person
+      extend ActiveModel::Translation
+    end
+  
+  {Learn more}[link:classes/ActiveModel/Translation.html]
+  
\ No newline at end of file
diff --git a/activemodel/lib/active_model/translation.rb b/activemodel/lib/active_model/translation.rb
index 2d2df269d0..2ab342ffac 100644
--- a/activemodel/lib/active_model/translation.rb
+++ b/activemodel/lib/active_model/translation.rb
@@ -1,6 +1,23 @@
 require 'active_support/core_ext/hash/reverse_merge'
 
 module ActiveModel
+  
+  # ActiveModel::Translation provides integration between your object and
+  # the Rails internationalization (i18n) framework.
+  # 
+  # A minimal implementation could be:
+  # 
+  #   class TranslatedPerson
+  #     extend ActiveModel::Translation
+  #   end
+  # 
+  #   TranslatedPerson.human_attribute_name('my_attribue')
+  #   #=> "My attribute"
+  # 
+  # This also provides the required class methods for hooking into the
+  # Rails internationalization API, including being able to define a
+  # class based i18n_scope and lookup_ancestors to find translations in
+  # parent classes.
   module Translation
     include ActiveModel::Naming
 
@@ -18,8 +35,6 @@ module ActiveModel
 
     # Transforms attributes names into a more human format, such as "First name" instead of "first_name".
     #
-    # Example:
-    #
     #   Person.human_attribute_name("first_name") # => "First name"
     #
     # Specify +options+ with additional translating options.