i18n

Instruction file imported from wintermeyer/cursor-rails-rules (.cursor/rules/i18n.mdc). Copyright stays with the author.

Base I18n Standards

We always assume that the application supports multiple languages and locales. By default we go with English as the primary language and German as the secondary language.

Check if the 'rails-i18n' gem is installed. If not add it to the Gemfile:

gem 'rails-i18n', '~> 8.0.0'

and run a bundle install.

Configuration

1. Setup

# config/application.rb
config.i18n.default_locale = :en
config.i18n.available_locales = [:en, :de]
config.i18n.fallbacks = true

2. Directory Structure

config/locales/
├── en/
│   ├── models/
│   ├── views/
│   └── controllers/
└── de/
    ├── models/
    ├── views/
    └── controllers/

Key Structure

1. Namespace Hierarchy

en:
  models:      # Model-specific translations
  views:       # View-specific translations
  controllers: # Controller-specific messages
  helpers:     # Form helpers and labels
  common:      # Shared translations

2. Key Naming

• Use lowercase
• Use dots for nesting
• Use underscores for words
• Keep keys descriptive
• Follow Ruby naming conventions

Implementation

1. In Views

<%= t('.title') %>                     # Lazy lookup
<%= t('views.users.index.title') %>    # Full key
<%= t('.welcome', name: @user.name) %> # With interpolation

2. In Controllers

flash[:notice] = t('.success')
redirect_back_or_to root_path, notice: t('.created')

3. In Models

validates :status, inclusion: { in: %w[pending active],
  message: ->(object, data) { I18n.t("models.#{object.class.name.downcase}.errors.invalid_status") } }

4. In Mailers

mail(
  to: @user.email,
  subject: t('.welcome_subject', name: @user.name)
)

Best Practices

1. Key Organization

• Group by feature/module
• Use consistent nesting levels
• Keep keys short but meaningful
• Document non-obvious keys

2. Translation Management

• Use YAML for static content
• Use Ruby for dynamic content
• Keep translations DRY
• Regular sync with translators

3. Performance

• Use lazy lookup when possible
• Cache common translations
• Avoid deep nesting
• Preload translations in production

4. Quality Assurance

• Test all locales
• Verify interpolations
• Check for missing keys
• Review context usage

Common Patterns

1. Pluralization

en:
  items:
    zero: "No items"
    one: "One item"
    other: "%{count} items"

2. Interpolation

en:
  welcome: "Welcome, %{name}!"
  count: "Found %{count} %{model}"

3. HTML Content

en:
  instructions_html: "Please read our <a href='%{url}'>terms</a>"

4. Scoped Translations

# In a Users controller action
t('.not_found', scope: 'controllers.users')

Maintenance

1. Regular Tasks

• Update missing translations
• Remove unused keys
• Verify key consistency

2. Documentation

• Document special cases
• Keep locale list updated
• Track translation versions