로캘에 맞게 값 서식 지정하기
표시에 필요한 단위와 시간 정보를 전달하고, 내장 Intl로 숫자, 날짜, 목록, 텍스트의 서식을 지정하세요.
번역된 메시지에도 가격, 날짜, 수량, 목록 같은 값이 들어갑니다. Lingo 객체는 카탈로그에서 값을 조회하지 않고 활성 로캘에 맞게 값의 서식을 지정합니다. 메시지와 값에 같은 로캘을 적용하려면 주변 메시지를 렌더링하는 객체를 그대로 사용하세요.
숫자와 수량 #
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const price = l.currency(29.99, "USD");
const completion = l.percent(0.125, { maximumFractionDigits: 1 });
const temperature = l.unit(32, "celsius", { unitDisplay: "long" });가격 서식은 입력한 미국 달러 금액의 표시 형식만 바꾸며, 통화를 환산하지는 않습니다. 백분율 입력값은 비율이므로 0.125은 12.5%로 표시되고, 12.5은 1250%를 의미합니다. 마찬가지로 단위 도우미도 입력한 섭씨 값을 환산하지 않고 단위만 붙입니다.
| 메서드 | 값 뒤에 전달하는 매개변수 |
|---|---|
num(value: number) | Intl.NumberFormatOptions(선택 사항). |
currency(value: number, currency: string) | 통화 코드, 이어서 숫자 서식 옵션(선택 사항). |
percent(value: number) | 숫자 서식 옵션(선택 사항). |
unit(value: number, unit: string) | 단위 식별자, 이어서 숫자 서식 옵션(선택 사항). |
compact(value: number) | 숫자 서식 옵션(선택 사항). |
fileSize(bytes: number) | 옵션 없음. |
모든 메서드는 문자열을 반환합니다. 통화, 백분율, 단위 메서드는 각 이름에 해당하는 스타일을 반드시 적용합니다. compact은 다른 옵션을 적용한 뒤 축약 표기법을 반드시 적용합니다.
fileSize은 값을 1024의 거듭제곱으로 나누고 고정 레이블 B, KB, MB, GB, TB, PB을 사용합니다. 숫자는 로캘에 맞게 표시하며, 바이트는 소수점 이하 자릿수 없이, 더 큰 단위는 소수점 이하 최대 한 자리까지 표시합니다. 1024은 1 KB로, 0은 0 B으로 표시됩니다. 바이트 수는 0 이상의 정수로 입력하세요. 음수나 소수 바이트 입력값에는 적절한 표시 정책이 없으며, GB 같은 레이블은 프랑스어 Go로 번역되지 않습니다.
날짜, 시간, 상대 오프셋 #
const instant = new Date("2026-10-10T12:00:00Z");
const timestamp = l.datetime(instant, { timeZone: "UTC" });
const date = l.date(instant, {
year: "numeric",
month: "2-digit",
day: "2-digit",
timeZone: "UTC",
});
const age = l.relative(-3, "day", { numeric: "auto" });이 호출에서는 이전 예제의 l을 사용합니다. date, time, datetime는 Date | number를 받고, 그 뒤에 Intl.DateTimeFormatOptions을 선택적으로 받습니다. 숫자 타임스탬프의 단위는 유닉스 초가 아니라 밀리초입니다. 기본값은 각각 중간 길이의 날짜, 짧은 시간, 그리고 이 둘의 조합입니다.
year이나 hour 같은 개별 필드를 지정하면 기본 스타일이 적용되지 않습니다. 스타일 옵션을 명시하면 기본값을 재정의할 수 있지만, 서로 호환되지 않는 스타일과 개별 필드를 조합하면 내장 Intl에서 예외가 발생할 수 있습니다. 서버와 브라우저에서 같은 날짜를 표시해야 한다면 시간대를 설정하세요.
relative(value, unit, options?)은 부호 있는 숫자, Intl.RelativeTimeFormatUnit, 선택 사항인 Intl.RelativeTimeFormatOptions을 받아 입력한 오프셋의 서식을 지정합니다. 기준 시점과의 차이는 애플리케이션 코드에서 계산하고 필요할 때 갱신하세요. 이 메서드는 현재 시각을 읽거나 갱신을 예약하지 않습니다.
목록과 텍스트 작업 #
| 메서드 | 결과와 동작 |
|---|---|
list(items: string[], options?: Intl.ListFormatOptions) | 이미 선택된 레이블을 연결한 문자열. 기본적으로 접속사를 사용합니다. |
displayName(code, type) | 현지화된 이름 또는 undefined. 유형은 language, region, script, currency 중 하나입니다. 내장 대체 동작에 따라 코드 자체가 반환될 수 있습니다. |
sort(items: string[], options?: Intl.CollatorOptions) | 로캘의 정렬 규칙에 따라 정렬된 새 배열. 입력값은 변경되지 않습니다. |
segment(text, granularity?) | 기본값인 grapheme 또는 word/sentence을 기준으로 나눈 문자열 세그먼트. 단어 모드에는 공백 세그먼트도 포함됩니다. |
displayName은 내장 기능에서 발생한 오류를 처리하고 undefined를 반환합니다. 다른 메서드는 이와 같은 오류 처리를 하지 않습니다. 로캘 코드와 옵션이 애플리케이션에 입력되는 지점에서 유효성을 검사하세요.
지원하는 런타임에 맞추기 #
이 도우미들은 내장 NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator, Segmenter에 처리를 위임합니다. 이 패키지는 누락된 내장 API를 대체하거나 모든 런타임의 로캘 데이터를 제공하지는 않습니다.
지원하는 서버와 브라우저에서 대표적인 값을 테스트하세요. ICU 데이터에 따라 문장 부호와 표기 관례가 달라질 수 있습니다. 하이드레이션 시에는 로캘뿐 아니라 타임스탬프, 시간대, 상대 시간의 기준 시점도 일관되게 유지하세요.