복수형, 날짜, 숫자 처리하기
값, 단위, 시간대는 애플리케이션에서 제어하고, 문법과 표시 형식은 로캘에 맡기세요.
항목 수를 표현할 때는 두 가지를 결정해야 합니다. 애플리케이션이 어떤 숫자를 의미하는지, 그리고 독자의 언어로 그 수량을 어떻게 표현할지입니다. 날짜와 금액도 같은 방식으로 구분해서 다뤄야 합니다. 문법, 구분 기호, 통화, 시간대를 의도에 맞게 선택할 수 있도록 렌더링할 때까지 값을 구조화된 상태로 유지하세요.
이 예제에서는 @lingo.dev/react을 사용합니다. 네이티브 리소스 시스템은 저마다의 메시지 구문과 생성기를 사용합니다. ICU와 비슷한 표기법을 쓴다고 해서 모든 런타임을 서로 바꿔 쓸 수 있는 것은 아닙니다.
포매터에 완전한 메시지 전달하기 #
LingoProvider 하위의 컴포넌트에서 숫자형 개수 값과 복수형 메시지를 함께 사용하세요.
const l = useLingo();
const label = l.plural(
count,
{ one: "# item", other: "# items" },
{ context: "Number of items in the shopping cart" },
);@lingo.dev/react에서 useLingo을 가져오세요. count은 애플리케이션의 숫자 값입니다. 런타임은 ICU 메시지를 구성하고 현재 로캘에 맞춰 카탈로그의 번역에 서식을 적용합니다. one과 other는 문법 범주입니다. 서식이 적용된 숫자 뒤에 번역된 명사를 이어 붙이면 이 범주를 선택할 수도, 어순을 바꿀 수도 없게 됩니다.
plural 헬퍼는 이름이 지정된 CLDR 범주를 구성하지만, =0처럼 특정 숫자에 정확히 대응하는 분기는 포함하지 않습니다. 수량이 0일 때 제품에 맞는 메시지를 표시하려면 텍스트 처리 경로에서 명시적인 ICU 표현식을 사용하세요.
l.text("{count, plural, =0 {No items} one {# item} other {# items}}", {
context: "Cart count with a distinct empty state",
values: { count },
});대상 언어에는 영어보다 더 많은 범주가 필요할 수 있습니다. 모든 언어를 원문의 분기에 억지로 맞추지 말고, 번역된 메시지를 살펴보면서 해당 로캘이 선택하는 형식을 테스트하세요. 지원되는 형식과 추출 동작은 복수형과 선택 분기 문서에서 확인할 수 있습니다.
의미에 따라 메시지를 선택하려면 변하지 않는 선택자 값을 사용하세요.
l.select(role, {
admin: "Manage team settings",
member: "View team settings",
other: "View settings",
}, { context: "Settings action for the user's team role" });애플리케이션은 role을 제공합니다. admin, member, 필수 대체 분기인 other는 그대로 유지하고 각 분기의 메시지를 번역하세요. 알 수 없는 값에는 other가 사용됩니다.
순서를 나타내는 서수와 수량을 나타내는 기수 구분하기 #
서수는 순서를 나타냅니다. 다음과 같은 메시지에는 텍스트 처리 경로의 복합 ICU 포매터를 사용하세요.
l.text("You finished {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}", {
context: "Participant's finishing position in a competition",
values: { position },
});이 접미사는 영어 원문에 쓰이는 표현이지, 모든 언어에 적용되는 규칙이 아닙니다. 번역문에서는 대상 언어에 맞는 방식으로 순서를 표현해야 합니다. values을 제공하면 텍스트 처리 경로에서 서식을 지정할 수 있습니다. 생성된 선언은 호출 규약을 확인하지만, 중첩된 모든 ICU 분기를 검증하지는 않습니다.
통화와 백분율 단위를 명확히 지정하기 #
숫자형 금액 값과 해당 통화 코드를 함께 사용하세요.
const price = l.currency(1234.5, "EUR");
const discount = l.percent(0.15);첫 번째 호출은 금액을 유로 형식으로 표시할 뿐, 다른 통화를 유로로 환전하지는 않습니다. 두 번째 호출은 입력값이 분수 형태의 비율이므로 15퍼센트를 나타냅니다. 15을 제공하면 다른 수량을 의미하게 됩니다. 이렇게 서식이 적용된 문자열을 문장에 넣을 때는 새 원문 문자열을 조합하지 말고, 이름이 지정된 values을 통해 전달하세요.
서식 지정 헬퍼는 숫자, 단위, 목록을 비롯해 Intl 기반의 다른 값도 처리합니다. 각 헬퍼의 기본값과 지원 옵션을 확인하세요. 로캘에 맞게 서식을 지정한다고 해서 모든 사용자 지정 단위의 표시 문구까지 번역되는 것은 아니며, 잘못된 옵션을 사용하면 여전히 오류가 발생할 수 있습니다.
날짜의 의미와 표시 시간대 선택하기 #
타임스탬프는 특정 시점을 나타내지만, 달력 날짜는 시간대와 무관한 하루를 나타낼 수 있습니다. 제품에서 의도한 의미에 맞는 경우가 아니라면, 날짜만 있는 마감일을 자정이라는 특정 시점으로 변환하지 마세요.
특정 시점을 표시할 때는 의도한 표시 시간대를 지정하세요.
const instant = new Date("2026-01-02T00:30:00Z");
const date = l.date(instant, { timeZone: "UTC" });
const time = l.time(instant, { timeZone: "UTC" });이 헬퍼들은 표시 형식에 현재 로캘을 사용하고, 표시 시간대에는 UTC를 사용합니다. 기반이 되는 표준 API를 직접 사용할 수도 있습니다.
new Intl.NumberFormat("de-DE", {
style: "currency", currency: "EUR",
}).format(1234.5);
new Intl.DateTimeFormat("en-US", {
dateStyle: "medium", timeZone: "UTC",
}).format(new Date("2026-01-02T00:30:00Z"));서식과 상호작용이 있는 메시지는 지원되는 문법 안에서 작성하기 #
l.rich은 이름이 지정된 태그를 React 컴포넌트에 연결하고 단순한 플레이스홀더에 값을 삽입합니다. l.text의 복합 ICU 포매터는 사용하지 않습니다. 코드에서 링크 렌더러와 지역 값을 제공하면 “{region} 지역의 <link>배송 정책</link>을 읽어 보세요”와 같은 문장을 이 처리 경로에서 사용할 수 있습니다. 여기에 복수형이나 서수를 추가해도 ICU가 지원되는 것은 아닙니다.
상호작용은 코드에서 정의하고, 서식 구조와 문법을 함께 다뤄야 할 때는 지원되는 방식으로 메시지를 설계하세요. 알 수 없는 태그는 텍스트 그대로 남으며, 같은 이름의 태그를 중첩하면 태그 쌍을 연결하는 동작에 제약이 있습니다. 서식과 상호작용이 있는 메시지를 참고하세요.
의미가 달라지는 경우 확인하기 #
개수가 0, 1, 2, 더 큰 수인 경우를 테스트하고, 제품에서 소수를 허용한다면 소수도 테스트하세요. 영어 서수에는 1, 2, 3, 11, 12, 13, 21을 포함하고, 대상 언어에는 각 로캘에 맞는 예상 표현을 사용하세요. 알 수 없는 선택자, 의미상 음수가 가능한 금액, 자정 무렵의 동일한 시점을 두 시간대로 표시하는 경우도 테스트하세요.
이러한 테스트에는 실제 대상 언어 카탈로그를 불러오세요. 번역이 없거나 비어 있으면 원문으로 대체될 수 있으므로, 출력이 그럴듯하다는 이유만으로 대상 언어의 번역이 갖춰졌다고 판단할 수는 없습니다. 렌더링된 값을 의도한 수량, 날짜, 메시지와 비교한 다음, 언어 표현 자체도 검토하세요.