Rails Panda I18n

A Rails gem that provides automatic internationalization (i18n) support for Rails applications. It automatically detects user locale from URL parameters, cookies, or HTTP Accept-Language headers, and seamlessly integrates with Rails' URL helpers.

• Automatic locale detection from multiple sources (priority order):
  1. URL parameters (e.g., ?hl=pt)
  2. Cookies
  3. HTTP Accept-Language header
• Automatic locale setting via before_action callback
• URL helper integration - automatically adds locale parameter to all generated URLs
• Cookie persistence - saves user's language preference in a cookie (1 year expiration)
• Fully configurable - enable/disable features as needed
• Rails 7.0+ compatible (required for Ruby 3.2+ support)

Add this line to your application's Gemfile:

gem "rails-panda-i18n"

And then execute:

$ bundle install

The gem automatically includes itself in ActionController::Base, so no explicit inclusion is needed. Simply configure it in your ApplicationController:

class ApplicationController < ActionController::Base
  use_rails_panda_i18n
end

That's it! The gem will now:

• Detect locale from URL parameters, cookies, or HTTP headers
• Set I18n.locale automatically on each request
• Add the locale parameter to all generated URLs

You can customize the behavior with various options:

class ApplicationController < ActionController::Base
  use_rails_panda_i18n(
    # Cookie support
    enable_cookie_support: true,  # Enable/disable cookie support
    cookie_name: :hl,              # Cookie name (default: :hl)

    # Parameter support
    enable_param_support: true,    # Enable/disable parameter support
    param_name: :hl,               # Parameter name (default: :hl)

    # URL options
    setup_default_url_options: true,              # Enable URL helper integration
    setup_class_default_url_options: true,        # Add to class-level default_url_options
    setup_instance_default_url_options: true,     # Add to instance-level default_url_options

    # Automatic locale setting
    setup_locale_on_before_action: true  # Automatically set locale via before_action
  )
end

class ApplicationController < ActionController::Base
  use_rails_panda_i18n(
    cookie_name: :language,
    param_name: :lang
  )
end

Now the locale will be detected from ?lang=pt and stored in a language cookie.

class ApplicationController < ActionController::Base
  use_rails_panda_i18n(
    enable_cookie_support: false
  )
end

class ApplicationController < ActionController::Base
  use_rails_panda_i18n(
    enable_param_support: false
  )
end

If you want to set the locale manually instead of using the before_action:

class ApplicationController < ActionController::Base
  use_rails_panda_i18n(
    setup_locale_on_before_action: false
  )

  before_action :set_locale

  private

  def set_locale
    locale = rails_panda__get_user_locale || I18n.default_locale
    I18n.locale = locale
  end
end

class ApplicationController < ActionController::Base
  use_rails_panda_i18n(
    setup_default_url_options: false
  )
end

The gem detects locale in the following order:

1. URL Parameter - If present and valid (e.g., ?hl=pt)
2. Cookie - If present and valid
3. HTTP Accept-Language Header - Falls back to browser's language preference

Only locales in I18n.available_locales are considered valid.

When enabled, the gem automatically adds the locale parameter to all URLs generated by Rails URL helpers:

# If current locale is :pt
root_path
# => "/?hl=pt"

users_path
# => "/users?hl=pt"

This works with both class-level and instance-level default_url_options.

The gem provides several methods you can use in your controllers:

Returns the detected user locale (as a symbol) or nil if none found:

def show
  locale = rails_panda__get_user_locale
  # => :pt, :en, etc. or nil
end

Adds the current locale to a hash of URL options:

options = { controller: "users", action: "index" }
rails_panda__add_ui_language_to(options)
# => { controller: "users", action: "index", hl: :pt }

Sets the locale and cookie (if cookie support is enabled):

rails_panda__set_locale
# Sets I18n.locale and cookie

• Ruby >= 3.2
• Rails >= 7.0 (required for Ruby 3.2+ support)
• http_accept_language gem (automatically included as a dependency)

Make sure you have configured I18n.available_locales in your Rails application:

# config/initializers/i18n.rb
I18n.available_locales = [:en, :pt, :es, :fr]
I18n.default_locale = :en

After checking out the repo, run bundle install to install dependencies. Then, run bundle exec rspec to run the tests.

Bug reports and pull requests are welcome on GitHub at https://github.com/bigbadpanda-tech/rails-panda-i18n.

The gem is available as open source under the terms of the MIT License.