콘텐츠와 현지화

원칙

• 하나에는 용어 하나만 쓰세요. 동작, 상태, 대상의 이름이 모든 화면에서 같아야 두 단어가 서로 다른 것처럼 보이지 않습니다.
• 결과를 먼저, 다음 단계를 이어서 쓰세요. 읽는 사람은 첫머리를 보고 움직이므로 오류 코드와 내부 용어는 세부 정보에 두세요.
• 문장 단위로 번역하세요. 어순과 복수 표현은 언어마다 다르므로 조각을 이어 문장을 만들지 마세요.
• 값은 사용자의 로케일과 시간대로 표시하세요. 첫 렌더링이 일치하도록 서버와 클라이언트 모두 Intl에 둘을 명시해 전달하세요.

인터페이스 문구

복구할 수 있는 오류는 원인과 해결 방법을 알리고 입력값을 유지합니다. 성공은 작업이 실제로 끝났을 때만 알리세요. 결과를 어디에 남기고 어떻게 알릴지는 접근성에서 다룹니다.

한국어 문구는 설명에 -합니다, 안내에 -하세요를 쓰고, 단위는 숫자에 붙이며(검사 2개), -에 대한이나 -을 통해 같은 번역투를 피합니다.

숫자, 날짜, 시간대

로케일은 숫자와 날짜 형식을, 시간대는 순간의 현지 시각을 정합니다. 아래에서 둘을 바꾸고 DST 변경 전후 시각을 UTC 원본과 비교해 보세요. 통화는 USD로 고정입니다.

원본: 2026-03-08T06:30:00Z. 상대 시간은 현재 시각이 아닌 고정된 기준을 씁니다.

잘못된 날짜, NaN, 지원하지 않는 로케일은 데이터 경계에서 검증하고 오류로 처리하세요. 빈 값을 0이나 현재 시각으로 표시하지 마세요. 표시용 문자열을 다시 값으로 파싱하지 마세요.

const locale = userPreferences.locale
const timeZone = userPreferences.timeZone
// value is an instant with a known offset; never parse an ambiguous local string.
const occurredAt = new Date('2026-03-08T07:30:00Z')
const display = new Intl.DateTimeFormat(locale, {
  timeZone,
  dateStyle: 'medium',
  timeStyle: 'long',
}).format(occurredAt)

<time dateTime={occurredAt.toISOString()}>{display}</time>

// formatNumber, formatCurrency and formatPercent from @surflane/ui keep zero
// and write a missing value as you name it.
const countLabel = formatNumber(count, {
  locale,
  missing: messages.notAvailable,
})

ECMA-402 — Intl 형식

언어와 방향

lang은 언어를, dir은 읽는 방향을 정합니다. 사용자가 입력한 이름은 dir="auto"로, 라틴 문자 식별자는 bdi dir="ltr"로 격리하세요. RTL 미리보기는 레이아웃만 확인합니다.

텍스트는 자르지 말고 줄을 바꾸고, 여백은 start와 end 방향으로 주세요. 컬렉션 카드마다 놓인 마지막 메시지처럼 비슷한 항목이 같은 높이를 지켜야 하면 Text lines={2}로 줄 수를 제한하고, 전체 글은 항목을 여는 곳에서 보여 주세요. 오류와 확인 문구에서 이름, 금액, 식별자를 말줄임표로 숨기지 마세요.

W3C — 언어 선언 / W3C — 텍스트 방향

컴포넌트 레이블

컴포넌트는 닫기·복사 버튼의 이름, 업로드 알림, 차트의 데이터 표처럼 직접 쓰는 글이 있습니다. 인스턴스마다 넘기지 말고 LabelsProvider로 앱에서 한 번 번역하세요. @surflane/ui/labels-ko의 KoreanLabels는 이 글을 모두 한국어로 씁니다.

import { KoreanLabels } from '@surflane/ui/labels-ko'
import { LabelsProvider } from '@surflane/ui/labels'

// Every component inside writes in Korean.
<KoreanLabels>{children}</KoreanLabels>

// Change some labels for one part of the app; the rest carry on.
<LabelsProvider labels={{ dialog: { close: '창 닫기' } }}>
  {children}
</LabelsProvider>

컴포넌트에 직접 준 속성이 provider의 레이블보다, provider의 레이블이 컴포넌트의 영어 기본값보다 우선합니다. provider 안의 provider는 이름을 준 묶음만 바꾸고 나머지는 그대로 둡니다.

KoreanLabels는 함수를 받지 않아서 Server Component에서 렌더링할 수 있습니다. Breadcrumbs와 Spinner는 서버에서 렌더링되므로 이름을 속성으로 받습니다.

관련 문서

• 접근성 — 모든 화면이 지킬 WCAG 2.2 AA 기준을 정합니다.
• 타이포그래피 — 글꼴, 타입 역할, 줄 길이, 한국어 조판 규칙을 정합니다.
• Number Field — 증가·감소로 숫자 범위를 조절합니다.
• Date / time picker — 로케일별 형식으로 날짜, 시간, 범위를 입력받습니다.