@@ -329,7 +329,7 @@ $ rails g controller comments This will generate the following things: -```bash +``` create app/controllers/blorgh/comments_controller.rb invoke erb exist app/views/blorgh/comments @@ -373,7 +373,7 @@ This partial will be responsible for rendering just the comment text, for now. C <%= comment_counter + 1 %>. <%= comment.text %> ``` -The `comment_counter` local variable is given to us by the `<%= render @post.comments %>` call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created. +The `comment_counter` local variable is given to us by the `<%= render @post.comments %>` call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created. That completes the comment function of the blogging engine. Now it's time to use it within an application. @@ -435,7 +435,7 @@ Copied migration [timestamp_1]_create_blorgh_posts.rb from blorgh Copied migration [timestamp_2]_create_blorgh_comments.rb from blorgh ``` -The first timestamp (`\[timestamp_1\]`) will be the current time and the second timestamp (`\[timestamp_2\]`) will be the current time plus a second. The reason for this is so that the migrations for the engine are run after any existing migrations in the application. +The first timestamp (`[timestamp_1]`) will be the current time and the second timestamp (`[timestamp_2]`) will be the current time plus a second. The reason for this is so that the migrations for the engine are run after any existing migrations in the application. To run these migrations within the context of the application, simply run `rake db:migrate`. When accessing the engine through `http://localhost:3000/blog`, the posts will be empty. This is because the table created inside the application is different from the one created within the engine. Go ahead, play around with the newly mounted engine. You'll find that it's the same as when it was only an engine. @@ -471,7 +471,7 @@ Also, to keep it simple, the posts form will have a new text field called `autho First, the `author_name` text field needs to be added to the `app/views/blorgh/posts/_form.html.erb` partial inside the engine. This can be added above the `title` field with this code: -```erb +```html+erb

<%= f.label :author_name %>
<%= f.text_field :author_name %> @@ -528,14 +528,14 @@ Now with all the pieces in place, an action will take place that will associate Finally, the author's name should be displayed on the post's page. Add this code above the "Title" output inside `app/views/blorgh/posts/show.html.erb`: -```erb +```html+erb

Author: <%= @post.author %>

``` -By outputting `@post.author` using the `<%=` tag, the `to_s` method will be called on the object. By default, this will look quite ugly: +By outputting `@post.author` using the `<%=` tag, the `to_s` method will be called on the object. By default, this will look quite ugly: ``` # @@ -786,7 +786,7 @@ You can override this view in the application by simply creating a new file at ` Try this now by creating a new file at `app/views/blorgh/posts/index.html.erb` and put this content in it: -```erb +```html+erb

Posts

<%= link_to "New Post", new_post_path %> <% @posts.each do |post| %> diff --git a/guides/source/form_helpers.md b/guides/source/form_helpers.md index d6f401dfa1..5c73b51a51 100644 --- a/guides/source/form_helpers.md +++ b/guides/source/form_helpers.md @@ -29,7 +29,7 @@ The most basic form helper is `form_tag`. <% end %> ``` -When called without arguments like this, it creates a `<form>` tag which, when submitted, will POST to the current page. For instance, assuming the current page is `/home/index`, the generated HTML will look like this (some line breaks added for readability): +When called without arguments like this, it creates a ` ``` -Now, you'll notice that the HTML contains something extra: a `div` element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name `utf8` enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are [GET" or "POST". The second input element with name `authenticity_token` is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the "Security Guide](./security.html#cross-site-request-forgery-csrf). +Now, you'll notice that the HTML contains something extra: a `div` element with two hidden input elements inside. This div is important, because the form cannot be successfully submitted without it. The first input element with name `utf8` enforces browsers to properly respect your form's character encoding and is generated for all forms whether their actions are "GET" or "POST". The second input element with name `authenticity_token` is a security feature of Rails called *cross-site request forgery protection*, and form helpers generate it for every non-GET form (provided that this security feature is enabled). You can read more about this in the [Security Guide](./security.html#cross-site-request-forgery-csrf). NOTE: Throughout this guide, the `div` with the hidden input elements will be excluded from code samples for brevity. @@ -49,10 +49,10 @@ NOTE: Throughout this guide, the `div` with the hidden input elements will be ex One of the most basic forms you see on the web is a search form. This form contains: -# a form element with "GET" method, -# a label for the input, -# a text input element, and -# a submit element. +* a form element with "GET" method, +* a label for the input, +* a text input element, and +* a submit element. To create this form you will use `form_tag`, `label_tag`, `text_field_tag`, and `submit_tag`, respectively. Like this: @@ -100,7 +100,7 @@ form_tag({:controller => "people", :action => "search"}, :method => "get", :clas ### Helpers for Generating Form Elements -Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as `text_field_tag` and `check_box_tag`), generate just a single `<input>` element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the `params` hash in the controller with the value entered by the user for that field. For example, if the form contains `<%= text_field_tag(:query) %>`, then you would be able to get the value of this field in the controller with `params[:query]`. +Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as `text_field_tag` and `check_box_tag`), generate just a single `` element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the `params` hash in the controller with the value entered by the user for that field. For example, if the form contains `<%= text_field_tag(:query) %>`, then you would be able to get the value of this field in the controller with `params[:query]`. When naming inputs, Rails uses certain conventions that make it possible to submit parameters with non-scalar values such as arrays or hashes, which will also be accessible in `params`. You can read more about them in [chapter 7 of this guide](#understanding-parameter-naming-conventions). For details on the precise usage of these helpers, please refer to the [API documentation](http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html). @@ -245,10 +245,10 @@ The corresponding view `app/views/articles/new.html.erb` using `form_for` looks There are a few things to note here: -# `@article` is the actual object being edited. -# There is a single hash of options. Routing options are passed in the `:url` hash, HTML options are passed in the `:html` hash. Also you can provide a `:namespace` option for your form to ensure uniqueness of id attributes on form elements. The namespace attribute will be prefixed with underscore on the generated HTML id. -# The `form_for` method yields a *form builder* object (the `f` variable). -# Methods to create form controls are called *on* the form builder object `f` +* `@article` is the actual object being edited. +* There is a single hash of options. Routing options are passed in the `:url` hash, HTML options are passed in the `:html` hash. Also you can provide a `:namespace` option for your form to ensure uniqueness of id attributes on form elements. The namespace attribute will be prefixed with underscore on the generated HTML id. +* The `form_for` method yields a *form builder* object (the `f` variable). +* Methods to create form controls are called *on* the form builder object `f` The resulting HTML is: @@ -260,11 +260,11 @@ The resulting HTML is: ``` -The name passed to `form_for` controls the key used in `params` to access the form's values. Here the name is `article` and so all the inputs have names of the form `article[attribute_name]`. Accordingly, in the `create` action `params[:article]` will be a hash with keys `:title` and `:body`. You can read more about the significance of input names in the parameter_names section. +The name passed to `form_for` controls the key used in `params` to access the form's values. Here the name is `article` and so all the inputs have names of the form `article[attribute_name]`. Accordingly, in the `create` action `params[:article]` will be a hash with keys `:title` and `:body`. You can read more about the significance of input names in the parameter_names section. The helper methods called on the form builder are identical to the model object helpers except that it is not necessary to specify which object is being edited since this is already managed by the form builder. -You can create a similar binding without actually creating `<form>` tags with the `fields_for` helper. This is useful for editing additional model objects with the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for creating both like so: +You can create a similar binding without actually creating `

` tags with the `fields_for` helper. This is useful for editing additional model objects with the same form. For example if you had a Person model with an associated ContactDetail model you could create a form for creating both like so: ```erb <%= form_for @person, :url => { :action => "create" } do |person_form| %> @@ -387,7 +387,7 @@ The most generic helper is `select_tag`, which -- as the name implies -- simply This is a start, but it doesn't dynamically create the option tags. You can generate option tags with the `options_for_select` helper: -```erb +```html+erb <%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...]) %> output: @@ -407,7 +407,7 @@ Knowing this, you can combine `select_tag` and `options_for_select` to achieve t `options_for_select` allows you to pre-select an option by passing its value. -```erb +```html+erb <%= options_for_select([['Lisbon', 1], ['Madrid', 2], ...], 2) %> output: @@ -425,7 +425,7 @@ WARNING: when `:inlude_blank` or `:prompt:` are not present, `:include_blank` is You can add arbitrary attributes to the options using hashes: -```erb +```html+erb <%= options_for_select([['Lisbon', 1, :'data-size' => '2.8 million'], ['Madrid', 2, :'data-size' => '3.2 million']], 2) %> output: @@ -502,8 +502,8 @@ Using Date and Time Form Helpers You can choose not to use the form helpers generating HTML5 date and time input fields and use the alternative date and time helpers. These date and time helpers differ from all the other form helpers in two important respects: -# Dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc.) and so there is no single value in your `params` hash with your date or time. -# Other helpers use the `_tag` suffix to indicate whether a helper is a barebones helper or one that operates on model objects. With dates and times, `select_date`, `select_time` and `select_datetime` are the barebones helpers, `date_select`, `time_select` and `datetime_select` are the equivalent model object helpers. +* Dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc.) and so there is no single value in your `params` hash with your date or time. +* Other helpers use the `_tag` suffix to indicate whether a helper is a barebones helper or one that operates on model objects. With dates and times, `select_date`, `select_time` and `select_datetime` are the barebones helpers, `date_select`, `time_select` and `datetime_select` are the equivalent model object helpers. Both of these families of helpers will create a series of select boxes for the different components (year, month, day etc.). @@ -810,7 +810,7 @@ Sometimes when you submit data to an external resource, like payment gateway, fi The same technique is available for the `form_for` too: ```erb -<%= form_for @invoice, :url => external_url, :authenticity_token => 'external_token' do |f| +<%= form_for @invoice, :url => external_url, :authenticity_token => 'external_token' do |f| %> Form contents <% end %> ``` @@ -818,7 +818,7 @@ The same technique is available for the `form_for` too: Or if you don't want to render an `authenticity_token` field: ```erb -<%= form_for @invoice, :url => external_url, :authenticity_token => false do |f| +<%= form_for @invoice, :url => external_url, :authenticity_token => false do |f| %> Form contents <% end %> ``` @@ -826,7 +826,7 @@ Or if you don't want to render an `authenticity_token` field: Building Complex Forms ---------------------- -Many apps grow beyond simple forms editing a single object. For example when creating a Person you might want to allow the user to (on the same form) create multiple address records (home, work, etc.). When later editing that person the user should be able to add, remove or amend addresses as necessary. +Many apps grow beyond simple forms editing a single object. For example when creating a Person you might want to allow the user to (on the same form) create multiple address records (home, work, etc.). When later editing that person the user should be able to add, remove or amend addresses as necessary. ### Configuring the Model @@ -852,7 +852,7 @@ This creates an `addresses_attributes=` method on `Person` that allows you to cr The following form allows a user to create a `Person` and its associated addresses. -```erb +```html+erb <%= form_for @person do |f| %> Addresses:

New Post

form builder

<%= f.label :title %>
@@ -373,7 +372,7 @@ like this is called "create", and so the form should be pointed to that action. Edit the `form_for` line inside `app/views/posts/new.html.erb` to look like this: -```erb +```html+erb <%= form_for :post, :url => { :action => :create } do |f| %> ``` @@ -568,7 +567,7 @@ variables to the view. Now, create a new file `app/view/posts/show.html.erb` with the following content: -```erb +```html+erb

Title: <%= @post.title %> @@ -605,7 +604,7 @@ end And then finally a view for this action, located at `app/views/posts/index.html.erb`: -```erb +```html+erb

Listing posts

Hello, Rails!

Title: <%= @post.title %> @@ -726,8 +725,7 @@ end These changes will ensure that all posts have a title that is at least five characters long. Rails can validate a variety of conditions in a model, including the presence or uniqueness of columns, their format, and the existence of associated objects. Validations are covered in detail -in "Active Record Validations and -Callbacks":active_record_validations_callbacks.html#validations-overview +in [Active Record Validations and Callbacks](active_record_validations_callbacks.html#validations-overview) With the validation now in place, when you call `@post.save` on an invalid post, it will return `false`. If you open `app/controllers/posts_controller.rb` @@ -765,12 +763,12 @@ form, but that's not very useful. You need to tell the user that something went wrong. To do that, you'll modify `app/views/posts/new.html.erb` to check for error messages: -```erb +```html+erb <%= form_for :post, :url => { :action => :create } do |f| %> <% if @post.errors.any? %>

<%= pluralize(@post.errors.count, "error") %> prohibited - this post from being saved:

+ this post from being saved:

<%= msg %>

Editing post

<%= pluralize(@post.errors.count, "error") %> prohibited - this post from being saved:

+ this post from being saved:

<%= msg %>

<%= @user.name %>

@@ -1027,7 +1022,7 @@ when building the form will be explained in just a moment. For now, let's update `app/views/posts/new.html.erb` view to use this new partial, rewriting it completely: -```erb +```html+erb

New post

<%= render 'form' %> @@ -1037,7 +1032,7 @@ completely: Then do the same for the `app/views/posts/edit.html.erb` view: -```erb +```html+erb

Edit post

<%= render 'form' %> @@ -1049,8 +1044,7 @@ Point your browser to [http://localhost:3000/posts/new](http://localhost:3000/po try creating a new post. Everything still works. Now try editing the post and you'll receive the following error: -!images/getting_started/undefined_method_post_path.png(Undefined method -post_path)! +![Undefined method post_path](images/getting_started/undefined_method_post_path.png) To understand this error, you need to understand how `form_for` works. When you pass an object to `form_for` and you don't specify a `:url` @@ -1131,10 +1125,10 @@ them from the database. Note that we don't need to add a view for this action since we're redirecting to the `index` action. Finally, add a 'destroy' link to your `index` action template -(+app/views/posts/index.html.erb) to wrap everything +(`app/views/posts/index.html.erb`) to wrap everything together. -```erb +```html+erb

Listing Posts

Title

Title: <%= @post.title %> @@ -1451,7 +1445,7 @@ using the `post_path(@post)` helper. As we have already seen, this calls the template. This is where we want the comment to show, so let's add that to the `app/views/posts/show.html.erb`. -```erb +```html+erb

Title: <%= @post.title %> @@ -1512,7 +1506,7 @@ First, we will make a comment partial to extract showing all the comments for th post. Create the file `app/views/comments/_comment.html.erb` and put the following into it: -```erb +```html+erb

Commenter: <%= comment.commenter %> @@ -1527,7 +1521,7 @@ following into it: Then you can change `app/views/posts/show.html.erb` to look like the following: -```erb +```html+erb

Title: <%= @post.title %> @@ -1571,7 +1565,7 @@ comment to a local variable named the same as the partial, in this case Let us also move that new comment section out to its own partial. Again, you create a file `app/views/comments/_form.html.erb` containing: -```erb +```html+erb <%= form_for([@post, @post.comments.build]) do |f| %>

<%= f.label :commenter %>
@@ -1589,7 +1583,7 @@ create a file `app/views/comments/_form.html.erb` containing: Then you make the `app/views/posts/show.html.erb` look like the following: -```erb +```html+erb

Title: <%= @post.title %> @@ -1625,7 +1619,7 @@ in the `CommentsController`. So first, let's add the delete link in the `app/views/comments/_comment.html.erb` partial: -```erb +```html+erb

Commenter: <%= comment.commenter %> @@ -1768,6 +1762,7 @@ not stored as UTF-8, it can occasionally result in these kinds of issues that cannot be automatically detected by Rails and corrected. Two very common sources of data that are not UTF-8: + * Your text editor: Most text editors (such as Textmate), default to saving files as UTF-8. If your text editor does not, this can result in special characters that you enter in your templates (such as é) to appear as a diamond with a question mark inside diff --git a/guides/source/i18n.md b/guides/source/i18n.md index b15d5d2089..5cee77b1f3 100644 --- a/guides/source/i18n.md +++ b/guides/source/i18n.md @@ -1,9 +1,9 @@ Rails Internationalization (I18n) API ===================================== -The Ruby I18n (shorthand for _internationalization_) gem which is shipped with Ruby on Rails (starting from Rails 2.2) provides an easy-to-use and extensible framework for *translating your application to a single custom language* other than English or for *providing multi-language support* in your application. +The Ruby I18n (shorthand for _internationalization_) gem which is shipped with Ruby on Rails (starting from Rails 2.2) provides an easy-to-use and extensible framework for **translating your application to a single custom language** other than English or for **providing multi-language support** in your application. -The process of "internationalization" usually means to abstract all strings and other locale specific bits (such as date or currency formats) out of your application. The process of "localization" means to provide translations and localized formats for these bits. [1] +The process of "internationalization" usually means to abstract all strings and other locale specific bits (such as date or currency formats) out of your application. The process of "localization" means to provide translations and localized formats for these bits.^[1](#footnote-1) So, in the process of _internationalizing_ your Rails application you have to: @@ -31,7 +31,7 @@ Internationalization is a complex problem. Natural languages differ in so many w * providing support for English and similar languages out of the box * making it easy to customize and extend everything for other languages -As part of this solution, *every static string in the Rails framework* -- e.g. Active Record validation messages, time and date formats -- *has been internationalized*, so _localization_ of a Rails application means "over-riding" these defaults. +As part of this solution, **every static string in the Rails framework** -- e.g. Active Record validation messages, time and date formats -- **has been internationalized**, so _localization_ of a Rails application means "over-riding" these defaults. ### The Overall Architecture of the Library @@ -81,7 +81,7 @@ There are just a few simple steps to get up and running with I18n support for yo Following the _convention over configuration_ philosophy, Rails will set up your application with reasonable defaults. If you need different settings, you can overwrite them easily. -Rails adds all `.rb` and `.yml` files from the `config/locales` directory to your *translations load path*, automatically. +Rails adds all `.rb` and `.yml` files from the `config/locales` directory to your **translations load path**, automatically. The default `en.yml` locale in this directory contains a sample pair of translation strings: @@ -92,11 +92,11 @@ en: This means, that in the `:en` locale, the key _hello_ will map to the _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance Active Record validation messages in the [`activerecord/lib/active_record/locale/en.yml`](https://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml file or time and date formats in the [`activesupport/lib/active_support/locale/en.yml`](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml) file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend. -The I18n library will use *English* as a *default locale*, i.e. if you don't set a different locale, `:en` will be used for looking up translations. +The I18n library will use **English** as a **default locale**, i.e. if you don't set a different locale, `:en` will be used for looking up translations. -NOTE: The i18n library takes a *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-GB`, 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 `:cs`, `: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-GB`, 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-GB` dictionary. Various [Rails I18n plugins](http://rails-i18n.org/wiki) such as [Globalize2](ht) +NOTE: The i18n library takes a **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-GB`, 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 `:cs`, `: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-GB`, 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-GB` dictionary. Various [Rails I18n plugins](http://rails-i18n.org/wiki) such as [Globalize2](ht) -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. +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. NOTE: The backend will lazy-load these translations when a translation is looked up for the first time. This makes it possible to just swap the backend with something else even after translations have already been announced. @@ -126,11 +126,11 @@ I18n.default_locale = :pt ### Setting and Passing the Locale -If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in `application.rb` or an initializer as shown above, and it will persist through the requests. +If you want to translate your Rails application to a **single language other than English** (the default locale), you can set I18n.default_locale to your locale in `application.rb` or an initializer as shown above, and it will persist through the requests. -However, you would probably like to *provide support for more locales* in your application. In such case, you need to set and pass the locale between requests. +However, you would probably like to **provide support for more locales** in your application. In such case, you need to set and pass the locale between requests. -WARNING: You may be tempted to store the chosen locale in a _session_ or a cookie, however *do not do this*. The locale should be transparent and a part of the URL. This way you won't break people's basic assumptions about the web itself: if you send a URL to a friend, they should see the same page and content as you. A fancy word for this would be that you're being [RESTful](http://en.wikipedia.org/wiki/Representational_State_Transfer. Read more about the RESTful approach in [Stefan Tilkov's articles](http://www.infoq.com/articles/rest-introduction). Sometimes there are exceptions to this rule and those are discussed below. +WARNING: You may be tempted to store the chosen locale in a _session_ or a cookie, however **do not do this**. The locale should be transparent and a part of the URL. This way you won't break people's basic assumptions about the web itself: if you send a URL to a friend, they should see the same page and content as you. A fancy word for this would be that you're being [RESTful](http://en.wikipedia.org/wiki/Representational_State_Transfer. Read more about the RESTful approach in [Stefan Tilkov's articles](http://www.infoq.com/articles/rest-introduction). Sometimes there are exceptions to this rule and those are discussed below. The _setting part_ is easy. You can set the locale in a `before_filter` in the `ApplicationController` like this: @@ -142,7 +142,7 @@ def set_locale end ``` -This requires you to pass the locale as a URL query parameter as in `http://example.com/books?locale=pt`. (This is, for example, Google's approach.) So `http://localhost:3000?locale=pt` will load the Portuguese localization, whereas `http://localhost:3000?locale=de` would load the German localization, and so on. You may skip the next section and head over to the *Internationalize your application* section, if you want to try things out by manually placing the locale in the URL and reloading the page. +This requires you to pass the locale as a URL query parameter as in `http://example.com/books?locale=pt`. (This is, for example, Google's approach.) So `http://localhost:3000?locale=pt` will load the Portuguese localization, whereas `http://localhost:3000?locale=de` would load the German localization, and so on. You may skip the next section and head over to the **Internationalize your application** section, if you want to try things out by manually placing the locale in the URL and reloading the page. Of course, you probably don't want to manually include the locale in every URL all over your application, or want the URLs look differently, e.g. the usual `http://example.com/pt/books` versus `http://example.com/en/books`. Let's discuss the different options you have. @@ -205,9 +205,9 @@ The most usual way of setting (and passing) the locale would be to include it in This approach has almost the same set of advantages as setting the locale from the domain name: namely that it's RESTful and in accord with the rest of the World Wide Web. It does require a little bit more work to implement, though. -Getting the locale from `params` and setting it accordingly is not hard; including it in every URL and thus *passing it through the requests* is. To include an explicit option in every URL (e.g. `link_to( books_url(:locale => I18n.locale))`) would be tedious and probably impossible, of course. +Getting the locale from `params` and setting it accordingly is not hard; including it in every URL and thus **passing it through the requests** is. To include an explicit option in every URL (e.g. `link_to( books_url(:locale => I18n.locale))`) would be tedious and probably impossible, of course. -Rails contains infrastructure for [centralizing dynamic decisions about the URLs" in its "`ApplicationController#default_url_options`](http://api.rubyonrails.org/classes/ActionController/Base.html#M000515, which is useful precisely in this scenario: it enables us to set "defaults" for [`url_for`](http://api.rubyonrails.org/classes/ActionController/Base.html#M000503) and helper methods dependent on it (by implementing/overriding this method). +Rails contains infrastructure for "centralizing dynamic decisions about the URLs" in its [`ApplicationController#default_url_options`](http://api.rubyonrails.org/classes/ActionController/Base.html#M000515, which is useful precisely in this scenario: it enables us to set "defaults" for [`url_for`](http://api.rubyonrails.org/classes/ActionController/Base.html#M000503) and helper methods dependent on it (by implementing/overriding this method). We can include something like this in our `ApplicationController` then: @@ -219,11 +219,11 @@ def default_url_options(options={}) end ``` -Every helper method dependent on `url_for` (e.g. helpers for named routes like `root_path` or `root_url`, resource routes like `books_path` or `books_url`, etc.) will now *automatically include the locale in the query string*, like this: `http://localhost:3001/?locale=ja`. +Every helper method dependent on `url_for` (e.g. helpers for named routes like `root_path` or `root_url`, resource routes like `books_path` or `books_url`, etc.) will now **automatically include the locale in the query string**, like this: `http://localhost:3001/?locale=ja`. You may be satisfied with this. It does impact the readability of URLs, though, when the locale "hangs" at the end of every URL in your application. Moreover, from the architectural standpoint, locale is usually hierarchically above the other parts of the application domain: and URLs should reflect this. -You probably want URLs to look like this: `www.example.com/en/books` (which loads the English locale) and `www.example.com/nl/books` (which loads the Dutch locale). This is achievable with the [over-riding `default_url_options`" strategy from above: you just have to set up your routes with "`scoping`](http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html) option in this way: +You probably want URLs to look like this: `www.example.com/en/books` (which loads the English locale) and `www.example.com/nl/books` (which loads the Dutch locale). This is achievable with the "over-riding `default_url_options`" strategy from above: you just have to set up your routes with [`scoping`](http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html) option in this way: ```ruby # config/routes.rb @@ -254,7 +254,7 @@ You would probably need to map URLs like these: match '/:locale' => 'dashboard#index' ``` -Do take special care about the *order of your routes*, so this route declaration does not "eat" other ones. (You may want to add it directly before the `root :to` declaration.) +Do take special care about the **order of your routes**, so this route declaration does not "eat" other ones. (You may want to add it directly before the `root :to` declaration.) NOTE: Have a look at two plugins which simplify work with routes in this way: Sven Fuchs's [routing_filter](https://github.com/svenfuchs/routing-filter/tree/master and Raul Murciano's [translate_routes](https://github.com/raul/translate_routes/tree/master). @@ -305,14 +305,18 @@ You most probably have something like this in one of your applications: Yourapp::Application.routes.draw do root :to => "home#index" end +``` +```ruby # app/controllers/home_controller.rb class HomeController < ApplicationController def index flash[:notice] = "Hello Flash" end end +``` +```html+erb # app/views/home/index.html.erb

Hello World

<%= flash[:notice] %>

<%=t :hello_world %>

<%= flash[:notice] %>

`. So let's add the missing translations into the dictionary files (i.e. do the "localization" part): @@ -373,10 +379,12 @@ You may use YAML (`.yml`) or plain Ruby (`.rb`) files for storing your translati You can use variables in the translation messages and pass their values from the view. -```ruby +```erb # app/views/home/index.html.erb <%=t 'greet_username', :user => "Bill", :message => "Goodbye" %> +``` +```yaml # config/locales/en.yml en: greet_username: "%{message}, %{user}!" @@ -384,9 +392,9 @@ en: ### Adding Date/Time Formats -OK! Now let's add a timestamp to the view, so we can demo the *date/time localization* feature as well. To localize the time format you pass the Time object to `I18n.l` or (preferably) use Rails' `#l` helper. You can pick a format by passing the `:format` option -- by default the `:default` format is used. +OK! Now let's add a timestamp to the view, so we can demo the **date/time localization** feature as well. To localize the time format you pass the Time object to `I18n.l` or (preferably) use Rails' `#l` helper. You can pick a format by passing the `:format` option -- by default the `:default` format is used. -```ruby +```erb # app/views/home/index.html.erb

<%=t :hello_world %>

<%= flash[:notice] %>

``` ### 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. +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. All options besides `:default` and `:scope` that are passed to `#translate` will be interpolated to the translation: @@ -629,14 +637,16 @@ I18n.default_locale = :de Keys with a '_html' suffix and keys named 'html' are marked as HTML safe. Use them in views without escaping. -```ruby +```yaml # config/locales/en.yml en: welcome: welcome! hello_html: hello! title: html: title! +``` +```html+erb # app/views/home/index.html.erb

<%= t('welcome') %>

<%= raw t('welcome') %>

@@ -649,7 +659,7 @@ en: How to Store your Custom Translations ------------------------------------- -The Simple backend shipped with Active Support allows you to store translations in both plain Ruby and YAML format. [2] +The Simple backend shipped with Active Support allows you to store translations in both plain Ruby and YAML format.^[2](#footnote-2) For example a Ruby Hash providing translations can look like this: @@ -850,7 +860,7 @@ Customize your I18n Setup ### Using Different Backends -For several reasons the Simple backend shipped with Active Support only does the "simplest thing that could possibly work" _for Ruby on Rails_ [3] ... which means that it is only guaranteed to work for English and, as a side effect, languages that are very similar to English. Also, the simple backend is only capable of reading translations but can not dynamically store them to any format. +For several reasons the Simple backend shipped with Active Support only does the "simplest thing that could possibly work" _for Ruby on Rails_^[3](#footnote-3) ... which means that it is only guaranteed to work for English and, as a side effect, languages that are very similar to English. Also, the simple backend is only capable of reading translations but can not dynamically store them to any format. That does not mean you're stuck with these limitations, though. The Ruby I18n gem makes it very easy to exchange the Simple backend implementation with something else that fits better for your needs. E.g. you could exchange it with Globalize's Static backend: @@ -960,8 +970,8 @@ If you found this guide useful, please consider recommending its authors on [wor Footnotes --------- -fn1. Or, to quote [Wikipedia](http://en.wikipedia.org/wiki/Internationalization_and_localization:) _"Internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. Localization is the process of adapting software for a specific region or language by adding locale-specific components and translating text."_ +[1]: Or, to quote [Wikipedia](http://en.wikipedia.org/wiki/Internationalization_and_localization:) _"Internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. Localization is the process of adapting software for a specific region or language by adding locale-specific components and translating text."_ -fn2. Other backends might allow or require to use other formats, e.g. a GetText backend might allow to read GetText files. +[2]: Other backends might allow or require to use other formats, e.g. a GetText backend might allow to read GetText files. -fn3. One of these reasons is that we don't want to imply any unnecessary load for applications that do not need any I18n capabilities, so we need to keep the I18n library as simple as possible for English. Another reason is that it is virtually impossible to implement a one-fits-all solution for all problems related to I18n for all existing languages. So a solution that allows us to exchange the entire implementation easily is appropriate anyway. This also makes it much easier to experiment with custom features and extensions. +[3]: One of these reasons is that we don't want to imply any unnecessary load for applications that do not need any I18n capabilities, so we need to keep the I18n library as simple as possible for English. Another reason is that it is virtually impossible to implement a one-fits-all solution for all problems related to I18n for all existing languages. So a solution that allows us to exchange the entire implementation easily is appropriate anyway. This also makes it much easier to experiment with custom features and extensions. diff --git a/guides/source/initialization.md b/guides/source/initialization.md index 203080cc1d..2e26937d47 100644 --- a/guides/source/initialization.md +++ b/guides/source/initialization.md @@ -16,8 +16,8 @@ server+ to boot your app. NOTE: Paths in this guide are relative to Rails or a Rails application unless otherwise specified. -TIP: If you want to follow along while browsing the Rails "source -code":https://github.com/rails/rails, we recommend that you use the `t` +TIP: If you want to follow along while browsing the Rails [source +code](https://github.com/rails/rails), we recommend that you use the `t` key binding to open the file finder inside GitHub and find files quickly. @@ -491,7 +491,7 @@ run <%= app_const %> The `Rack::Builder.parse_file` method here takes the content from this `config.ru` file and parses it using this code: ```ruby -app = eval "Rack::Builder.new {( " cfgfile "\n )}.to_app", +app = eval "Rack::Builder.new {( " + cfgfile + "\n )}.to_app", TOPLEVEL_BINDING, config ``` diff --git a/guides/source/layouts_and_rendering.md b/guides/source/layouts_and_rendering.md index 4f0caa3274..ecfd91a10b 100644 --- a/guides/source/layouts_and_rendering.md +++ b/guides/source/layouts_and_rendering.md @@ -43,7 +43,7 @@ resources :books And you have a view file `app/views/books/index.html.erb`: -```ruby +```html+erb

Books are coming soon!

``` @@ -63,7 +63,7 @@ Note that we don't have explicit render at the end of the index action in accord If we want to display the properties of all the books in our view, we can do so with an ERB template like this: -```ruby +```html+erb

Products

A Greeting for You!

Comments

New comment

Posts

New Post

Listing posts

Hello, Rails!

<%= pluralize(@post.errors.count, "error") %> prohibited - this post from being saved:

Editing post

<%= pluralize(@post.errors.count, "error") %> prohibited - this post from being saved:

<%= @user.name %>

New post

Edit post

Listing Posts

Hello World

<%=t :hello_world %>

<%=t :hello_world %>

Books are coming soon!

Listing Books

New zone

New zone

Editing zone

Editing zone

Products

Products

Products

Contacts

Contacts

Products