I18n

Translating will_paginate output

As of will_paginate v2.3.16 and v3.0, some output of will_paginate view helper and the complete output of page_entries_info helper can be translated by means of the i18n library.

In Rails, this usually means adding your translations in YAML or ruby format in the "config/locale/" directory.

Translation keys and default values for the will_paginate helper can be seen here:

en:
  will_paginate:
    previous_label: "← Previous"
    next_label: "Next →"
    page_gap: "…"

The HTML entities you see here are left arrow, right arrow and horizontal ellipsis for the gap between page numbers.

You can copy these over to your own application and change the values as you see fit, or translate them to other languages that you want to support.

Translating page_entries_info

Translations for page_entries_info helper are much more complex. Here are the defaults:

en:
  will_paginate:
    page_entries_info:
      single_page:
        zero:  "No %{model} found"
        one:   "Displaying 1 %{model}"
        other: "Displaying all %{count} %{model}"
      single_page_html:
        zero:  "No %{model} found"
        one:   "Displaying <b>1</b> %{model}"
        other: "Displaying <b>all&nbsp;%{count}</b> %{model}"

      multi_page: "Displaying %{model} %{from} - %{to} of %{count} in total"
      multi_page_html: "Displaying %{model} <b>%{from}&nbsp;-&nbsp;%{to}</b> of <b>%{count}</b> in total"

First of all, you'll notice the values are duplicated twice: one for plain text and one containing HTML tags. The keys for HTML variants end in "_html".

"single_page" and "multi_page" are referring to whether the paginated collection has only one page or more. In case there are more pages, the message is a little more verbose, stating the range of records displayed (e.g. "records 6 - 12 of 32 in total").

The %{model} value is the name of the paginated items in correct plural form. For instance, if you passed a collection of LineItem records, the "model" value would be "line item" or "line items". You can translate this value separately:

en:
  will_paginate:
    models:
      line_item:
        zero:  line items
        one:   line item
        few:   line items
        other: line items

However, you don't need to do this if you've translated your Active Record models using the official method:

en:
  activerecord:
    models:
      line_item:
        zero:  line items
        one:   line item
        # ...

You should translate your models using the latter method so that all helpers of your application could benefit from these translations, not just will_paginate.

Lastly, you can customize page_entries_info output per-model. Just nest the values under the model key:

en:
  will_paginate:
    line_item:
      page_entries_info:
        single_page:
          zero:  "Your shopping cart is empty"
          one:   "Displaying one item in your cart"
          other: "Displaying all %{count} items"
        multi_page: "Displaying items %{from} - %{to} of %{count} in total"

In the above example we provided translations for the LineItem model specifically. It will affect only calls that deal with LineItems, but not any others:

<%= page_entries_info @items, :model => LineItem, :html => false %>

We used :html => false here because the extra translations we provided above were plain text only. With only a bit of extra work you can copy those values to appropriate "*_html" keys and add HTML markup.