Merge branch 'master' of git@github.com:lifo/docrails

railties/guides/source/2_3_release_notes.textile

@@ -320,6 +320,7 @@ h4. Other Action Controller Changes
 * You can now use symbols for the +:type+ option of +send_file+ and +send_data+, like this: +send_file("fabulous.png", :type => :png)+.
 * The +:only+ and +:except+ options for +map.resources+ are no longer inherited by nested resources.
 * The bundled memcached client has been updated to version 1.6.4.99.
+* The +expires_in+, +stale?+, and +fresh_when+ methods now accept a +:public+ option to make them work well with proxy caching.
 
 h3. Action View
 
@@ -448,7 +449,7 @@ In most cases, you'll want template caching to be turned on in production, which
 config.action_view.cache_template_loading = true
 </ruby>
 
-This line will be generated for you by default in a new Rails 2.3 application. But please note: if you've upgraded from an older version of Rails, you won't have this setting in your +production.rb+ and template caching will be off by default. Unless you really need the ability to update templates in production without restarting the server, you should be sure to add this setting when you upgrade.
+This line will be generated for you by default in a new Rails 2.3 application. If you've upgraded from an older version of Rails, Rails will default to caching templates in production and test but not in development.
 
 h4. Other Action View Changes
 

railties/guides/source/caching_with_rails.textile

@@ -500,16 +500,17 @@ seriously considering optimizing their caching needs.
 Also the new "Cache money":http://github.com/nkallen/cache-money/tree/master plugin is supposed to be mad cool. 
 
 h3. References
- * "RailsEnvy, Rails Caching Tutorial, Part 1":http://www.railsenvy.com/2007/2/28/rails-caching-tutorial
- * "RailsEnvy, Rails Caching Tutorial, Part 1":http://www.railsenvy.com/2007/3/20/ruby-on-rails-caching-tutorial-part-2
- * "ActiveSupport::Cache documentation":http://api.rubyonrails.org/classes/ActiveSupport/Cache.html
- * "Rails 2.1 integrated caching tutorial":http://thewebfellas.com/blog/2008/6/9/rails-2-1-now-with-better-integrated-caching
 
+* "RailsEnvy, Rails Caching Tutorial, Part 1":http://www.railsenvy.com/2007/2/28/rails-caching-tutorial
+* "RailsEnvy, Rails Caching Tutorial, Part 1":http://www.railsenvy.com/2007/3/20/ruby-on-rails-caching-tutorial-part-2
+* "ActiveSupport::Cache documentation":http://api.rubyonrails.org/classes/ActiveSupport/Cache.html
+* "Rails 2.1 integrated caching tutorial":http://thewebfellas.com/blog/2008/6/9/rails-2-1-now-with-better-integrated-caching
 
 h3. Changelog
+
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/10-guide-to-caching
 
-February  22, 2009: Beefed up the section on cache_stores
-December  27, 2008: Typo fixes
-November  23, 2008: Incremental updates with various suggested changes and formatting cleanup
-September 15, 2008: Initial version by Aditya Chadha
+* February  22, 2009: Beefed up the section on cache_stores
+* December  27, 2008: Typo fixes
+* November  23, 2008: Incremental updates with various suggested changes and formatting cleanup
+* September 15, 2008: Initial version by Aditya Chadha

railties/guides/source/i18n.textile

@@ -91,7 +91,7 @@ This means, that in the +:en+ locale, the key _hello_ will map to _Hello world_
 
 The I18n library will use *English* as a *default locale*, ie. if you don't set a different locale, +:en+ will be used for looking up translations.
 
-NOTE: The i18n library takes *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". (For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have £. Also, insults would be different in American and British English :) Reason for this pragmatic approach is that most of the time, you usually care about making your application available in different "languages", and working with locales is much simpler this way. However, nothing stops you from separating regional and other settings in the traditional way. In this case, you could eg. inherit from the default +en+ locale and then provide UK specific settings in a +:en-UK+ dictionary.
+NOTE: The i18n library takes *pragmatic approach* to locale keys (after "some discussion":http://groups.google.com/group/rails-i18n/browse_thread/thread/14dede2c7dbe9470/80eec34395f64f3c?hl=en), including only the _locale_ ("language") part, like +:en+, +:pl+, not the _region_ part, like +:en-US+ or +:en-UK+, which are traditionally used for separating "languages" and "regional setting" or "dialects". Many international applications use only the "language" element of a locale such as +:cz+, +:th+ or +:es+ (for Czech, Thai and Spanish).  However, there are also regional differences within different language groups that may be important. For instance, in the +:en-US+ locale you would have $ as a currency symbol, while in +:en-UK+, you would have £. Nothing stops you from separating regional and other settings in this way: you just have to provide full "English - United Kingdom" locale in a +:en-UK+ dictionary. Various "Rails I18n plugins":http://rails-i18n.org/wiki such as "Globalize2":http://github.com/joshmh/globalize2 may help you implement it.
 
 The *translations load path* (+I18n.load_path+) is just a Ruby Array of paths to your translation files that will be loaded automatically and available in your application. You can pick whatever directory and translation file naming scheme makes sense for you.
 
@@ -414,9 +414,15 @@ So that would give you:
 
 TIP: Right now you might need to add some more date/time formats in order to make the I18n backend work as expected. Of course, there's a great chance that somebody already did all the work by *translating Rails's defaults for your locale*. See the "rails-i18n repository at Github":http://github.com/svenfuchs/rails-i18n/tree/master/rails/locale for an archive of various locale files. When you put such file(s) in +config/locale/+ directory, they will automatically ready for use.
 
+h4. Localized views
+
+Rails 2.3 brings one convenient feature: localized views (templates). Let's say you have a _BooksController_ in your application. Your _index_ action renders content in +app/views/books/index.html.erb+ template. When you put a _localized variant_ of this template: *+index.es.html.erb+* in the same directory, Rails will render content in this template, when the locale is set to +:es+. When the locale is set to the default locale, generic +index.html.erb+ view will be used. (Future Rails versions may well bring this _automagic_ localization to assets in +public+, etc.)
+
+You can make use this feature eg. when working with great amount of static content, which would be clumsy to put inside YAML or Ruby dictionaries. Bear in mind, though, that any change you would like to do later to the template must be propagated to all of them.
+
 h4. Organization of locale files
 
-When you are using the default SimpleStore, shipped with the i18n library, you store dictionaries in plain-text files on the disc. Putting translations for all parts of your application in one file per locale could be hard to manage. You can store these files in a hierarchy which makes sense to you.
+When you are using the default SimpleStore, shipped with the i18n library, dictionaries are stored in plain-text files on the disc. Putting translations for all parts of your application in one file per locale could be hard to manage. You can store these files in a hierarchy which makes sense to you.
 
 For example, your +config/locale+ directory could look like this:
 
@@ -443,9 +449,14 @@ For example, your +config/locale+ directory could look like this:
 |-----en.rb
 </pre>
 
-This way, you can separate model and model attribute names from text inside views, and all of this from the "defaults" (eg. date and time formats).
+This way, you can separate model and model attribute names from text inside views, and all of this from the "defaults" (eg. date and time formats). Other stores for the i18n library could provide different means of such separation.
+
+NOTE: The default locale loading mechanism in Rails does not load locale files in nested dictionaries, like we have here. So, for this to work, we must explicitely tell Rails to look further:
 
-Other stores for the i18n library could provide different means of such separation.
+<ruby>
+  # config/environment.rb
+  config.i18n.load_path += Dir[File.join(RAILS_ROOT, 'config', 'locales', '**', '*.{rb,yml}')]
+</ruby>
 
 Do check the "Rails i18n Wiki":http://rails-i18n.org/wiki for list of tools available for managing translations.
 
@@ -528,6 +539,23 @@ I18n.t 'active_record.error_messages'
 # => { :inclusion => "is not included in the list", :exclusion => ... }
 </ruby>
 
+h5. "Lazy" lookup
+
+Rails 2.3 implements convenient way to lookup locale inside _views_. When you have following dictionary:
+
+<yaml>
+es:
+  books:
+    index:
+      title: "Título"
+</yaml>
+
+you can lookup the +books.index.title+ value *inside* +app/views/books/index.html.erb+ template like this (note the dot): 
+
+<ruby>
+<%= t '.title' %>
+</ruby>
+
 h4. Interpolation
 
 In many cases you want to abstract your translations so that *variables can be interpolated into the translation*. For this reason the I18n API provides an interpolation feature.
@@ -677,20 +705,20 @@ end
 The key for the error message in this case is +:blank+. Active Record will lookup this key in the namespaces:
 
 <ruby>
-activerecord.errors.messages.models.[model_name].attributes.[attribute_name]
-activerecord.errors.messages.models.[model_name]
+activerecord.errors.models.[model_name].attributes.[attribute_name]
+activerecord.errors.models.[model_name]
 activerecord.errors.messages
 </ruby>
 
 Thus, in our example it will try the following keys in this order and return the first result:
 
 <ruby>
-activerecord.errors.messages.models.user.attributes.name.blank
-activerecord.errors.messages.models.user.blank
+activerecord.errors.models.user.attributes.name.blank
+activerecord.errors.models.user.blank
 activerecord.errors.messages.blank
 </ruby>
 
-When your models are additionally using inheritance then the messages are looked up for the inherited model class names are looked up.
+When your models are additionally using inheritance then the messages are looked up in the inheritance chain.
 
 For example, you might have an Admin model inheriting from User:
 

railties/guides/source/index.erb.textile

@@ -73,6 +73,10 @@ h3. Digging Deeper
 
 <dl>
 
+<% guide("Rails on Rack", 'rails_on_rack.html') do %>
+  This guide covers Rails integration with Rack and interfacing with other Rack components.
+<% end %>
+
 <% guide("Rails Internationalization API", 'i18n.html', :ticket => 23) do %>
   This guide covers how to add internationalization to your applications. Your application will be able to translate content to different languages, change pluralization rules, use correct date formats for each country and so on.
 <% end %>
@@ -109,8 +113,8 @@ h3. Digging Deeper
   This guide covers the command line tools and rake tasks provided by Rails.
 <% end %>
 
-<% guide("Rails on Rack", 'rails_on_rack.html', :ticket => 58) do %>
-  This guide covers Rails integration with Rack and interfacing with other Rack components.
+<% guide("Caching with Rails", 'caching_with_rails.html', :ticket => 10) do %>
+  Various caching techniques provided by Rails.
 <% end %>
 
 </dl>