Advanced Customization and Internationalization

will_paginate offers powerful ways to customize both the HTML output and the text content of the pagination controls.

Custom Link Renderer

For full control over the generated HTML, you can provide your own link renderer class. A renderer is a class that inherits from WillPaginate::ActionView::LinkRenderer (or a framework-specific equivalent) and implements methods to build the pagination elements.

This is useful for integrating with CSS frameworks like Bootstrap or Tailwind CSS, which often require specific class names and markup structures.

Steps to Create a Custom Renderer

1. Create a Renderer Class: Define a new class that inherits from the default renderer.
2. Override Methods: Override methods like html_container, page_number, previous_or_next_page, or gap to change the output.
3. Use the Renderer: Pass your new class to the will_paginate helper using the :renderer option.

Example: Bootstrap 5 Renderer

Here is a simplified example of how you might create a renderer that generates Bootstrap 5-compatible pagination markup.

# app/lib/bootstrap_pagination/renderer.rb
class BootstrapPagination::Renderer < WillPaginate::ActionView::LinkRenderer
  def container_attributes
    { class: 'pagination' }
  end

  def page_number(page)
    if page == current_page
      tag(:li, tag(:span, page, class: 'page-link'), class: 'page-item active')
    else
      tag(:li, link(page, page, rel: rel_value(page), class: 'page-link'), class: 'page-item')
    end
  end

  def previous_or_next_page(page, text, classname)
    if page
      tag(:li, link(text, page, class: 'page-link'), class: "page-item #{classname}")
    else
      tag(:li, tag(:span, text, class: 'page-link'), class: "page-item #{classname} disabled")
    end
  end

  def gap
    tag(:li, tag(:span, '...', class: 'page-link'), class: 'page-item disabled')
  end

  def html_container(html)
    tag(:ul, html, container_attributes)
  end
end

In your view:

<%= will_paginate @collection, renderer: BootstrapPagination::Renderer %>

Internationalization (I18n)

All text generated by the will_paginate helpers can be translated using Ruby's standard I18n library.

You can provide your own translations by adding a will_paginate key to your locale files (e.g., config/locales/en.yml).

Default English Translations

The gem includes these default translations:

en:
  will_paginate:
    previous_label: "← Previous"
    next_label: "Next →"
    page_gap: "…"
    page_entries_info:
      single_page:
        zero:  "No %{model} found"
        one:   "Displaying 1 %{model}"
        other: "Displaying all %{count} %{model}"
      multi_page: "Displaying %{model} %{from} - %{to} of %{count} in total"

Example: Spanish Translations

To translate the pagination controls to Spanish, you could create config/locales/es.yml:

es:
  will_paginate:
    previous_label: "« Anterior"
    next_label: "Siguiente »"
    page_entries_info:
      single_page:
        zero: "No se encontraron %{model}"
        one: "Mostrando 1 %{model}"
        other: "Mostrando los %{count} %{model}"
      multi_page: "Mostrando %{model} del %{from} al %{to} de un total de %{count}"

Model-Specific Translations

You can even provide custom translations for the page_entries_info helper on a per-model basis. If your model is Post, will_paginate will look for a post.page_entries_info key within the will_paginate scope before falling back to the default.

en:
  will_paginate:
    post:
      page_entries_info:
        multi_page: "Showing posts %{from} to %{to} of %{count}"