로캘 루트 YAML
하나의 로캘 루트 아래에 있는 값을 번역하고 루트 이름을 대상 언어에 맞게 변경합니다.
Rails는 YAML 파일의 루트에서 로캘을 읽습니다. 파일 이름이 checkout.es.yml이어도 루트가 en:이면 영어 리소스를 정의한 파일입니다. yaml-root-key 핸들러는 해당 루트 아래의 메시지를 번역하고 루트를 대상 로캘로 바꿔, 언어가 달라도 조회 경로를 일관되게 유지합니다.
로캘 래퍼와 메시지 경로 #
원본 카탈로그에는 보간 구문과 복수형 분기가 함께 포함될 수 있습니다.
en:
checkout:
greeting: Hello, %{name}
items:
one: One item
other: "%{count} items"메시지 경로는 checkout.greeting, checkout.items.one, checkout.items.other입니다. 이 경로에는 en이 포함되지 않으므로 영어 원본과 스페인어 번역본에서 같은 메시지를 식별할 수 있습니다. 대상 래퍼는 es로 바뀌고, checkout, one, other은 그대로 키로 유지됩니다.
보간 구문과 복수형 범주 이름은 애플리케이션이 따라야 할 규약의 일부입니다. 단어를 번역한다고 해서 Rails의 복수형 규칙이 설정되거나 대상 언어에 필요한 모든 범주가 추가되지는 않습니다. 리소스를 승인하기 전에 애플리케이션에서 관련 수량과 변수를 렌더링해 확인하세요.
파서는 스칼라 키와 그 아래의 매핑으로 이루어진 단일 루트 키-값 쌍을 요구합니다. 빈 로캘은 허용되지만 루트 바로 아래에 스칼라 메시지나 목록이 있으면 거부됩니다. 여러 로캘이 담긴 YAML 파일은 로캘별 파일로 나누세요. 모든 루트를 변경 없이 유지하려면 일반 YAML을 사용하세요. OpenAPI 명세에는 이 핸들러를 선택하지 마세요.
업데이트와 범위 제한 #
중첩된 문자열 값은 로캘 래퍼 아래의 경로를 기준으로 비교합니다. 현재 원본은 구조의 기준이 되고, 이전 원본과 기존 번역본은 변경되지 않은 값을 그대로 이어서 사용하는 데 쓰입니다. 주석과 앵커는 YAML 트리 직렬화를 거치며, 이 과정에서 서식이 정규화될 수 있습니다.
키나 용어로 범위를 제한하더라도 이전 원본이 제공되면 변경되지 않은 번역을 재사용할 수 있습니다. CLI의 --key은 저장된 기준본을 사용하며, --force을 추가해도 이 재사용 동작은 바뀌지 않습니다. 원하는 문구로 정확히 수정하려면 번역본을 직접 편집하세요. 지침을 변경한 뒤 파일을 다시 생성하려면 승인된 번역본을 저장하고, 범위를 지정한 전체 파일 --force을 --key 없이 사용한 다음 변경된 모든 메시지를 확인하세요.
키로 범위를 지정하면 범위 밖의 매핑 문자열 중 아직 처리되지 않은 항목이 생략될 수 있습니다. 시퀀스 요소는 위치가 밀리지 않도록 원본 값을 유지합니다. 특히 좁은 범위로 새 로캘을 만들 때는 파싱 성공 여부와 별개로 누락된 내용이 없는지 확인하세요.
로캘과 저장 위치 설정 #
.yml 또는 .yaml 원본에는 format: "yaml-root-key"을 명시적으로 설정하세요. 확장자만으로는 로캘 래퍼를 식별할 수 없습니다. 파일 패턴과 대상 파일 구조는 CLI 설정 및 GitHub에서 설명합니다.
재구성하려면 대상 로캘이 필요하며, 지정하지 않으면 실패합니다. CLI의 localeFormat은 경로 표기만 바꾸며 YAML 내부에 기록된 로캘은 바꾸지 않습니다. 저장 위치와 파일의 루트를 모두 확인한 다음 Rails를 통해 인사말과 복수형 메시지를 불러오세요. Rails 앱 현지화에서는 이 파일들을 요청별 로캘 선택, 헬퍼, 대체 동작과 연결하는 방법을 설명합니다.