Rails 앱 현지화하기
Rails 로캘 루트 YAML을 번역하고 조회, 보간, 복수형, 요청별 로캘 선택을 확인하세요.
Rails는 t와 I18n.t를 통해 메시지에 일관된 이름을 부여합니다. Lingo.dev로 이 이름에 연결된 YAML을 번역하면서, 조회와 보간, 로캘 선택은 계속 Rails에 맡길 수 있습니다. 인사말과 알림 개수부터 시작해 애플리케이션에서 사용하는 것과 동일한 헬퍼로 확인하세요.
Rails 로캘 파일에 원본 메시지 넣기 #
config/locales/en.yml 파일을 만들거나 기존 파일에 내용을 추가하세요.
en:
home:
index:
welcome: "Welcome, %{name}!"
cta: "Create an account"
notifications:
unread:
one: "One unread notification"
other: "%{count} unread notifications"app/views/home/index.html.erb의 인사말에는 뷰 경로를 기준으로 한 상대 조회를 사용할 수 있습니다.
<h1><%= t(".welcome", name: @user_name) %></h1>
<p><%= t("notifications.unread", count: @unread_count) %></p>뷰 경로에 따라 .welcome의 전체 키는 home.index.welcome가 됩니다. 호출부에서 name와 count 값을 전달하므로 번역에서도 이 보간 이름을 그대로 유지해야 합니다. one와 other 같은 복수형 키는 분기를 구분하므로 변경하지 마세요.
번역 범위를 넓혀 가면서 하드코딩된 나머지 뷰 레이블, 메일러 문구, 모델 오류 메시지를 적절한 로캘 네임스페이스로 옮기세요. 파일을 번역하면 그 파일의 메시지를 불러오는 호출부에만 영향을 줍니다.
로캘 루트 YAML 선택하기 #
Rails는 YAML 루트에서 로캘을 읽습니다. en.yml의 이름을 es.yml로 바꿔도 en:를 그대로 두면 여전히 영어 메시지로 정의됩니다. yaml-root-key 핸들러를 사용해 값을 번역하고 루트 이름도 함께 바꾸세요.
프로젝트 루트에서 CLI를 설치하고 연결하세요.
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es,fr --files 'config/locales/en.yml' --yes
lingo link.lingo/config.json에 기록된 조직 및 로컬라이제이션 엔진 식별자는 그대로 유지하세요. 해당 파일의 files 배열에는 프로젝트에서 사용하는 원본 항목을 설정하세요.
[
{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" },
{ "pattern": "config/locales/*.en.yml", "format": "yaml-root-key" }
]두 번째 항목은 번역된 다른 언어 파일은 제외하고 mailers.en.yml 같은 관심사별 파일을 선택합니다. 프로젝트에 이런 파일이 없다면 이 항목을 삭제하세요. 형식은 명시적으로 설정하세요. 일반 YAML 형식은 모든 루트를 유지하며, CLI로 YAML 원본을 검색하려면 형식을 명시적으로 선택해야 합니다. 단일 루트 매핑 요구 사항과 재구성 동작은 로캘 루트 YAML에서 설명합니다.
번역하고 불러온 값 확인하기 #
아직 없는 대상 파일을 생성하려면 다음을 실행하세요.
lingo push --backfill-missing --wait실행이 끝나면 config/locales/es.yml을 열어 루트가 es:인지 확인하세요. 중첩된 키와 보간 이름이 원본과 일치하는지도 확인하세요. 직렬화 후에는 주석, 앵커, 별칭도 살펴보세요. 원본 파일 구성이 다르면 명시적인 대상 경로가 필요할 수 있습니다.
Rails 콘솔이나 애플리케이션 테스트에서 로캘을 명시적으로 선택해 결과를 불러오세요.
I18n.with_locale(:es) do
puts I18n.t("home.index.welcome", name: "Alex", raise: true)
[0, 1, 2, 20].each do |count|
puts I18n.t("notifications.unread", count: count, raise: true)
end
end확인에 앞서 :en, :es, :fr을 사용 가능한 로캘로 설정하세요. 이 예제는 조회와 보간을 확인합니다. 문구가 의도한 인사말과 알림 개수를 제대로 전달하는지도 살펴보세요. 대상 언어에 따라 원본의 영어 형식 외에 복수형 규칙과 분기가 더 필요할 수 있습니다. 프랑스어도 같은 방식으로 확인하고, 애플리케이션에 메일러와 유효성 검사 네임스페이스를 추가할 때도 동일하게 확인하세요.
요청에서도 같은 로캘을 선택하도록 설정하기 #
Rails 설정에서 지원 로캘과 기본 로캘을 선언하세요. 지원 로캘 중에서 선택한 값을 사용해 요청 처리를 I18n.with_locale으로 감싸면 로캘 상태가 다른 요청으로 이어지지 않습니다.
/es 같은 URL을 사용하려면 params[:locale]를 읽는 컨트롤러와 라우트 범위를 모두 설정하세요. 생성되는 링크에도 로캘을 유지하세요. 애플리케이션에서 Accept-Language도 협상한다면 두 글자만 잘라 쓰지 말고 품질 가중치와 지역 태그를 파싱하세요. 사용자가 로캘을 직접 선택할 수 있다면 그 선택을 우선해야 합니다.
대체 동작은 신중하게 선택하세요. 대체 기능 덕분에 페이지를 계속 사용할 수 있어도 스페인어 메시지 누락이 드러나지 않을 수 있습니다. 따라서 이 기능에 의존하지 말고 필수 대상 항목을 확인하세요. 날짜와 시간은 미리 서식이 지정된 문자열을 번역하기보다, 적절한 경우 Rails의 l 헬퍼로 현지화하세요.
대상 언어 페이지를 직접 열어 보고, 탐색을 통해서도 이동해 보세요. Rails가 대상 네임스페이스를 선택하고 예상한 보간 값을 표시하며 더 긴 텍스트도 처리하는지 확인하세요. lingo check은 Rails YAML의 완전성을 확인하는 검사가 아닙니다. 승인 과정에서 Rails의 로딩과 렌더링, 언어 검토를 계속 수행하세요.
원본이 변경되어도 번역 유지하기 #
원본 파일, 승인된 대상 파일, 설정, .lingo/lock.json을 함께 보관하세요. 메시지를 변경한 뒤에는 lingo push --wait을 실행해 일반적인 변경분을 처리하고, 변경된 메시지를 바뀌지 않은 인접 메시지와 비교하세요. 원문이 바뀌지 않은 문구의 번역을 정확히 수정하려면 대상 파일을 직접 편집하세요. YAML 키 범위에서는 기존 번역이 재사용될 수 있습니다. 지침 변경 후 번역을 다시 생성하려면 번역 범위의 설명에 따라, 지정한 범위의 파일 전체를 교체하기 전에 승인된 대상 파일을 저장해 두세요.
로컬에서 수정한 대상 번역이 서로 다른 변경으로 덮어써지지 않도록 보호해야 한다면 --wait 없이 제출하고, lingo pull --dry-run를 확인한 뒤 제출에 사용한 checkout에서 결과를 가져오세요. 완료를 기다렸다가 결과를 다시 쓰는 방식은 이처럼 최신 상태를 기준으로 충돌을 확인하지 않습니다. 다른 checkout에서는 버전 관리를 통해 커밋된 번역을 받습니다. 검토한 번역 보존하기를 참조하세요.
로컬 작업 흐름이 정상적으로 작동하면 GitHub App 또는 지속적 통합 자동화를 선택하세요. 번역 변경분을 병합하기 전에 생성된 리소스에도 동일한 Rails 검사를 실행하세요.