Skip to main content

Rails i18n: Ruby on Rails 국제화 완벽 가이드

첫 로케일 파일부터 프로덕션까지, Rails I18n을 설정하고 t() 도우미를 사용하며 CLDR 복수형을 처리하고 흔한 문제를 해결한 뒤 스마트 로케일 폴백 체인을 추가해 보세요.

1

Rails I18n 아키텍처 이해

Rails에는 I18n gem이 내장되어 있어요. 번역 파일은 config/locales/에 YAML(기본값) 또는 Ruby 파일로 저장돼요. 프레임워크는 뷰, 컨트롤러, 모델, 메일러에서 t() 도우미(I18n.translate의 별칭)를 제공해요. Rails I18n은 의도적으로 단순하게 설계되어 기본 번역, 보간, 복수형을 바로 처리해요.

config/application.rb
# Rails includes i18n out of the box via the i18n gem
# config/application.rb
module MyApp
  class Application < Rails::Application
    # Default locale
    config.i18n.default_locale = :en

    # Available locales
    config.i18n.available_locales = [:en, :de, :ja, :es, :fr, :'pt-BR']

    # Fallback to default locale when translation is missing
    config.i18n.fallbacks = true

    # Load translations from nested directories
    config.i18n.load_path += Dir[Rails.root.join('config', 'locales', '**', '*.{rb,yml}')]
  end
end
config/routes.rb
# config/routes.rb
Rails.application.routes.draw do
  scope "/:locale", locale: /en|de|ja|es|fr|pt-BR/ do
    root "home#index"
    resources :products
  end

  root "home#index"
end

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  around_action :switch_locale

  private

  def switch_locale(&action)
    locale = params[:locale] || I18n.default_locale
    I18n.with_locale(locale, &action)
  end

  def default_url_options
    { locale: I18n.locale }
  end
end
Rails는 config/locales/의 모든 .yml 및 .rb 파일을 자동으로 로드해요. 언어별(en.yml, de.yml), 기능별(en/users.yml, en/orders.yml) 또는 두 기준 모두(en/users.yml, de/users.yml) 원하는 방식으로 구성할 수 있어요. Rails가 시작할 때 모든 파일을 병합해요.
2

로케일 설정 구성

config/application.rb 또는 초기화 파일에서 default_locale, available_locales, 폴백 동작을 설정하세요. ApplicationController에서 before_action을 사용해 URL, 세션, 쿠키 또는 Accept-Language 헤더에서 로케일을 가져와 설정하도록 로케일 감지를 구성하세요.

config/locales/en.yml
# config/locales/en.yml
en:
  nav:
    home: "Home"
    about: "About"
    settings: "Settings"
  greeting: "Hello, %{name}!"
  cart:
    item_count:
      one: "%{count} item"
      other: "%{count} items"

# config/locales/de.yml
de:
  nav:
    home: "Startseite"
    about: "Über uns"
    settings: "Einstellungen"
  greeting: "Hallo, %{name}!"
  cart:
    item_count:
      one: "%{count} Artikel"
      other: "%{count} Artikel"
before_action에서 I18n.locale을 설정하는 것은 요청별로 안전하지만 런타임에 I18n.default_locale을 설정하면 전역으로 적용되어 모든 스레드에 영향을 줘요. 요청 범위의 로케일 변경에는 항상 스레드 로컬인 I18n.locale을 사용하고 I18n.default_locale은 사용하지 마세요.
3

t() 도우미 사용

t() 도우미는 뷰, 컨트롤러, 모델, 메일러, 작업 등 Rails 어디에서나 사용할 수 있어요. 키, 선택 사항인 보간 변수, 기본값이나 범위 같은 옵션을 받아요. 뷰에서는 현재 컨트롤러와 작업을 기준으로 키 범위를 자동 지정하는 지연 조회를 지원해요.

app/views/example.html.erb
# In views (ERB)
<h1><%= t('nav.home') %></h1>
<p><%= t('greeting', name: @user.name) %></p>

# In controllers
flash[:notice] = t('flash.product_created')

# In models
validates :name, presence: { message: I18n.t('errors.blank') }

# With HTML (safe)
<%= t('terms_html', link: link_to(t('terms_link'), '/terms')) %>
4

복수형 처리

Rails I18n은 zero, one, two, few, many, other라는 CLDR 복수형 범주를 사용해요. 영어에는 one과 other만 필요하지만 다른 언어에는 더 많은 형식이 필요해요. 대상 언어에 필요한 count 범주 아래에 복수형 번역을 중첩 YAML 키로 정의하세요.

Plural forms
# In YAML:
en:
  cart:
    item_count:
      zero: "No items"
      one: "%{count} item"
      other: "%{count} items"

# Arabic (6 forms):
ar:
  cart:
    item_count:
      zero: "لا عناصر"
      one: "عنصر واحد"
      two: "عنصران"
      few: "%{count} عناصر"
      many: "%{count} عنصرًا"
      other: "%{count} عنصر"

# Usage in views:
<%= t('cart.item_count', count: @cart.items.size) %>
활성 로케일에 필요한 복수형 범주가 없으면 Rails가 I18n::InvalidPluralizationData 오류를 발생시켜요. 러시아어 로케일에 영어에서 복사한 one과 other만 정의하면 2, 3, 4 같은 개수를 처리할 때 오류가 발생해요. 러시아어에는 few 범주가 필요하기 때문이에요. 언어마다 필요한 CLDR 범주를 항상 모두 정의하세요.
5

로케일 폴백 체인 추가

Rails의 내장 I18n.fallbacks는 지역 로케일에서 기본 로케일로 넘어가는 기본 폴백만 제공해요. pt-BR 사용자는 키가 누락되면 pt-PT 대신 영어를 보게 돼요. rails-locale-chain은 설정 가능한 딥 머지 체인을 추가해 지역 사용자가 가장 가까운 번역을 볼 수 있게 해요.

Lazy lookups
# Lazy lookups use the controller/action as scope
# app/views/products/index.html.erb
# Instead of t('products.index.title'), just use:
<h1><%= t('.title') %></h1>
<p><%= t('.description') %></p>

# Rails looks up: products.index.title and products.index.description

# config/locales/en.yml
en:
  products:
    index:
      title: "All Products"
      description: "Browse our catalog"
rails-locale-chain에는 11개 언어군을 아우르는 기본 제공 폴백 체인이 75개 이상 포함되어 있어요. Gemfile에 추가하고 초기화 파일에서 설정하면 지역 사용자에게 영어가 섞여 표시되는 대신 상위 로케일 번역이 바로 표시돼요.
6

번역 자동화

Rails I18n 설정이 끝나면 AI로 YAML 로케일 파일을 번역하세요. i18n Agent는 YAML을 기본으로 지원해요. 원본 로케일 파일을 지정하면 중첩 키, 보간 변수, 복수형을 보존하면서 모든 대상 언어 파일을 생성해요.

config/initializers/locale_chain.rb
# Gemfile
gem 'rails-locale-chain'

# config/initializers/locale_chain.rb
Rails.application.config.i18n.fallbacks = {
  'pt-BR': ['pt', 'en'],
  'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
  'es-419': ['es', 'en'],
}

# The gem deep-merges translations across the chain
# pt-BR -> pt -> en
# Missing keys in pt-BR are filled from pt, then en
점진적으로 번역하세요. 새 키를 추가하면 변경분만 번역하세요. 기존 번역을 보존하고 변경되지 않은 문자열을 불필요하게 다시 생성하지 않아도 돼요.

흔한 실수

InvalidPluralizationData 오류

필요한 CLDR 복수형 범주가 없으면 Rails가 I18n::InvalidPluralizationData 오류로 중단돼요. 영어 복수형(one/other)을 더 많은 범주가 필요한 언어에 복사할 때 가장 자주 발생해요. 러시아어에는 few가, 아랍어에는 zero/two/few/many가 필요해요. 올바른 CLDR 규칙을 위해 rails-i18n을 설치하고 모든 범주를 정의하세요.

뷰 밖에서 지연 조회 사용

지연 조회(t('.key'))는 Rails가 컨트롤러와 작업을 아는 뷰에서만 작동해요. 모델, 메일러, 서비스 객체에서 t('.key')를 사용하면 누락된 번역 오류가 발생해요. 뷰 밖에서는 전체 키(t('users.show.key'))를 사용하세요.

모든 번역을 망가뜨리는 YAML 구문 오류

잘못된 들여쓰기, 따옴표로 감싸지 않은 특수 문자, 공백 대신 탭 사용 같은 YAML 구문 오류 하나만 있어도 전체 로케일 파일을 로드하지 못해요. 해당 파일의 모든 번역이 누락된 키 오류를 반환해요. CI에서 린터로 YAML 파일을 검증하고 콜론, 대괄호, 선행 특수 문자가 있는 문자열은 따옴표로 감싸세요.

지금 i18n Agent 사용해 보기

번역 파일을 여기에 드롭

JSON, YAML, PO, XML, CSV, Markdown, Properties

또는 클릭하여 파일 선택

대상 언어

가입 불필요즉시 견적

Rails i18n FAQ