DEV Community: Karine Vieira

Internacionalização com GetText no Rails

Karine Vieira — Tue, 20 May 2025 12:13:00 +0000

Quando pensamos em internacionalização (i18n) em projetos Rails, a abordagem mais comum é utilizar a API nativa do framework com chaves de tradução. No entanto, recentemente descobri uma alternativa que torna esse processo mais direto e com maior visibilidade do conteúdo traduzido: o uso do GetText.

GetText é um framework utilizado no ecossistema Linux, que oferece um conjunto de ferramentas para facilitar a tradução de textos em aplicações. Integrado ao Rails, ele permite uma forma mais automática de localizar strings, sem a necessidade de criar e gerenciar nomes de chaves.

No modelo tradicional com I18n, criamos chaves de tradução e mapeamos seus conteúdos em arquivos YML. Nas views, essas chaves são utilizadas da seguinte forma:

t(".empty_state_message")
# => Nenhum resultado encontrado

Já com GetText, podemos escrever diretamente o texto original:

_("Nenhum resultado encontrado")
# => Nenhum resultado encontrado

Essa abordagem destaca imediatamente o conteúdo que será traduzido, tornando o código mais legível e intuitivo.

Setup

Instalação das Gems

Para integrar o GetText ao Rails, instalei as gems gettext_i18n_rails e gettext. Apesar de gettext ser uma dependência opcional da gettext_i18n_rails, vale a pena incluí-la no projeto, pois ela oferece rake tasks bastante úteis:

Para adicionar suporte a um novo idioma:

LANGUAGE=xx rake gettext:add_language

Substitua xx pelo código do idioma desejado, por exemplo, en para inglês. A lista completa dos idiomas suportados está disponível aqui.

Para buscar traduções ausentes e adicioná-las aos arquivos .po:

rake gettext:find

Configurações iniciais

Depois da instalação, é necessário criar um initializer para definir os domínios de tradução e os idiomas disponíveis. Para isso, usamos classes da gem fast_gettext, já que gettext_i18n_rails atua como um wrapper para facilitar a integração do GetText com projetos Rails.

# config/initializers/gettext_i18n_rails.rb
FastGettext.add_text_domain "app", path: "locale", type: :po
FastGettext.default_available_locales = ["pt_BR", "en", "es"]
FastGettext.default_text_domain = "app"

Essa configuração permite organizar as traduções por domínio. No exemplo acima, usei apenas o domínio app para fins de demonstração, mas é possível definir domínios separados por módulos da aplicação, evitando centralizar todas as traduções em um único arquivo.

Além disso, ajuste o before_action responsável por definir o idioma da aplicação para também atualizar o locale do GetText:

 def set_locale
   locale = params[:locale] || I18n.default_locale

+  FastGettext.set_locale(locale)
   I18n.locale = locale
 end

Por fim, como a aplicação já estava usando I18n para mensagens de erro do ActiveRecord (e alterar isso demandaria mais esforço), desativei esse comportamento do GetText:

# config/initializers/gettext_i18n_rails.rb
Rails.application.config.gettext_i18n_rails.use_for_active_record_attributes = false

Processo de tradução

Para iniciar o processo de tradução, adicionei um texto usando o método do GetText:

<%= _("Nenhum resultado encontrado") %>

Em seguida, executei a rake task:

rake gettext:find

Essa rake task escaneia o projeto e adiciona as novas strings aos arquivos .po.

Depois, incluí a tradução correspondente no campo msgstr de cada arquivo .po:

 # locale/en/app.po

 msgid "Nenhum resultado encontrado"
-msgstr ""
+msgstr "No result found"

Após atualizar as traduções, é importante rodar a rake task novamente. Isso garante que os arquivos edit.po sejam atualizados corretamente. Caso contrário, as alterações podem se misturar com novas strings adicionadas posteriormente, o que dificulta o controle de versões e a revisão das mudanças.

Features

Fallback automático

Se uma string não tiver tradução, ou se você esquecer de adicionar, o GetText retorna o valor original por padrão:

_("Nenhuma categoria encontrada")
# => Nenhuma categoria encontrada

Também é possível fornecer um bloco. Se esse bloco for passado, seu conteúdo será retornado como valor padrão, o que permite definir um fallback mais explícito:

_("Não foi encontrada uma tradução") { "Texto alternativo" }
# => Texto alternativo

Pluralização

A pluralização no GetText é semelhante à do I18n do Rails. Para que funcione corretamente, é necessário configurar a regra de plural de cada idioma nos arquivos .po.

No meu caso, os idiomas configurados ficaram assim:

# locale/en/app.po
- "Plural-Forms: nplurals=; plural=;\n"
+ "Plural-Forms: nplurals=2; plural=(n != 1);\n"

# locale/es/app.po
- "Plural-Forms: nplurals=; plural=;\n"
+ "Plural-Forms: nplurals=2; plural=(n != 1);\n"

# locale/pt_BR/app.po
- "Plural-Forms: nplurals=; plural=;\n"
+ "Plural-Forms: nplurals=2; plural=(n != 1);\n"

Depois disso, basta usar o método n_ passando o singular, o plural e o número.

n_("tarefa pendente", "tarefas pendentes", @total)

Após rodar a rake task gettext:find , serão geradas as entradas necessárias nos arquivos .po . Com as chaves criadas, é só adicionar as traduções correspondentes.

Traduções dinâmicas

É possível interpolar variáveis dentro das strings normalmente. O conteúdo será exibido dinamicamente:

_("Publicado por %{username}") % { username: @user.username }

Conclusão

Se você busca uma forma mais simples e direta de gerenciar traduções, vale a pena experimentar o GetText no seu projeto Rails. A integração é tranquila, o ganho em produtividade é real e você ainda pode manter o I18n do Rails para casos onde preferir.

Referências

Solving URL Length Issues in Rails Filters and Pagination

Karine Vieira — Sat, 22 Feb 2025 19:42:52 +0000

I’m writing this post because every solution I found involved JavaScript— but I refused to go down that path...

So, in a project I'm working on, we have a listing of contacts that allows filtering and paging. Among the filter options, we include a list of checkboxes for the client’s categories. Until now, we were making a GET request to apply the filters, and everything was working fine—until a client with more than 100 categories started using the page.

The Problem: URL Length Limits

When using GET requests, filter parameters are sent via Query Params, which append data directly to the URL. While this approach works well for a small number of filters, it becomes problematic as the number of selected options grows. Some browsers and web servers impose strict limits on the maximum URL length they can handle, and exceeding these limits can lead to errors.

For example, Google Chrome limits URLs to a maximum length of 2MB. On the server side, web servers like NGINX limits URLs to 8 KB (8,192 characters) via the large_client_header_buffers directive. If a request exceeds this size, NGINX returns a 414 (URI Too Long) error.

In our case, since each selected category was appended to the URL as a separate query parameter:

?filter[category_ids][]=1&filter[category_ids][]=2&filter[category_ids][]=3... # and so on

the URL quickly grew beyond acceptable limits, leading to a 414 (URI Too Long) error.

Changing the Request to POST

To prevent excessively long URLs, the first step was to change the request from GET to POST, since POST allows us to send data in the request body, keeping the URL short.

In the routes file, we needed to add a POST route pointing to the controller's index action:

resources :contacts, only: %i[index new create edit update destroy] do
  post :filter, on: :collection, action: :index # renamed the route to avoid conflicts
end

Next, we updated the form:

form_with(url: filter_contacts_path, method: :post, ...) do
  # ...
end

So far, so good.

New Issue: Pagination

When trying to use filters along with pagination, we encountered the following error:

ActionController::RoutingError (No route matches [GET] "/contacts/filter"):

Pagy makes a GET request, but now we needed the request to be POST.

Additionally, I noticed that when no filters were applied, the generated link pointed to contacts_path (which needs to be GET). However, when filters were active, the URL was filter_contacts_path (which needs to be POST).

To simplify this, I set filter_contacts_path as the default, ensuring the request was always POST. In the controller, I added request_path:

def index
  pagy, posts = pagy(Contact.some_scope, limit: 10, request_path: filter_contacts_path)
end

This fixed the RoutingError, but introduced a new issue:

New Issue: Filters Are Lost on Pagination

The filter was only applied to the first page. When navigating to the second page, the filters disappeared because the parameters were not being sent in the request body. This happens because pagination generates links, not forms.

Solution: Using `button_to`

The adopted strategy was to use button_to, as it generates hidden inputs with the received parameters, ensuring the filters are maintained while navigating through pages.

Now, following the Pagy example, the necessary changes would be applied:

<nav class="pagy nav" aria-label="Pages">
  <%# Previous page link %>
  <% if pagy.prev %>
-   <%= link_to(pagy_url_for(pagy, pagy.prev), { aria_label: "Previous" }) do %>
+   <%= button_to(
+     pagy_url_for(pagy, pagy.prev),
+     { params: request.params.except(:page), aria_label: "Previous" }
+   ) do %>
      &lt;
    <% end %>
  <% end %>

  <%# Page links %>
  <% pagy.series.each do |item| %>
    <% if item.is_a?(Integer) %>
-     <%= link_to(pagy_url_for(pagy, item)) do %>
+     <%= button_to(pagy_url_for(pagy, item), params: request.params.except(:page)) do %>
        <%= item %>
      <% end %>
    <% elsif item.is_a?(String) %>
-     <a role="link" aria-disabled="true" aria-current="page" class="current"><%= item %></a>
+     <%= button_to(nil, { params: request.params.except(:page), aria_current: "page", disabled: true, class: "current" }) do %>
        <%= item %>
      <% end %>
    <% elsif item == :gap %>
-     <a role="link" aria-disabled="true" class="gap">&hellip;</a>
+     <%= button_to(nil, { params: request.params.except(:page), disabled: true, class: "gap" }) do %>
        &hellip;
      <% end %>
    <% end %>
  <% end %>

  <%# Next page link %>
  <% if pagy.next %>
-   <%= link_to(pagy_url_for(pagy, pagy.next)), { aria_label: 'Next' }) do %>
+   <%= button_to(
+     pagy_url_for(pagy, pagy.next),
+     { params: request.params.except(:page), aria_label: "next" }
+   ) do %>
      &gt;
    <% end %>
  <% end %>
</nav>

Additionally, it was necessary to remove the page parameter from the request, as it was being sent in two ways:

As a hidden field (indicating the current page)
In the URL (indicating the next page)

If we didn’t remove it, Rails would end up using the current page instead of the next one.

And that’s it! 🎉 Now the page works normally, without gigantic URLs and without adding JavaScript code.