Content and localization

Principles

• Use one term for each thing. An action, state, or object keeps its name on every screen, so two words never seem to mean two things.
• Lead with the outcome, then the next step. Readers act on the first words they see, so keep error codes and internal terms in details.
• Translate whole sentences. Word order and plurals differ by language, so never build a sentence from fragments.
• Format values in the reader's locale and time zone. Pass both to Intl explicitly, with the same values on the server and the client, so the first render matches.

Interface text

A recoverable error names the cause and the fix, and keeps what the reader entered. Report success only when the work is done. Accessibility covers where results stay and how they are announced.

Korean copy describes with -합니다 and instructs with -하세요, attaches a counter to its numeral (검사 2개), and avoids translationese such as -에 대한 and -을 통해.

Numbers, dates, and time zones

The locale sets number and date formats, and the time zone sets an instant's local time. Change both below, and compare the times around a DST change with the UTC source. Currency stays USD.

Source: 2026-03-08T06:30:00Z. The relative time uses a fixed reference, not the current time.

Validate invalid dates, NaN, and unsupported locales at the data boundary, and treat them as errors. Don't show zero or the current time for a missing value. Never parse a display string back into a value.

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 formatting

Language and direction

lang sets the language, and dir sets the reading direction. Isolate names that readers enter with dir="auto", and Latin identifiers with bdi dir="ltr". The RTL preview checks layout only.

Wrap text instead of truncating it, and use start and end spacing. Where like items keep one height, such as the last message on each card of a collection, Text lines={2} clamps it, and the whole text shows where the item opens. Don't hide names, amounts, or identifiers behind an ellipsis in errors and confirmations.

W3C — Language declarations / W3C — Text direction

Component labels

Components write some text of their own: the names of close and copy buttons, the announcements of an upload, a chart's data table. Translate it once for the app with LabelsProvider, instead of on every instance. KoreanLabels from @surflane/ui/labels-ko writes all of it in Korean.

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>

A component's own props win over the provider's labels, and those over the component's English defaults. A provider inside another changes the groups it names and keeps the rest.

KoreanLabels takes no functions, so a Server Component can render it. Breadcrumbs and Spinner render on the server and take their names as props.

Related

• Accessibility — Sets the WCAG 2.2 AA baseline that every screen meets.
• Typography — Sets typefaces, type roles, line length, and Korean text rules.
• Number Field — Controls a numeric range with increment and decrement.
• Date / time picker — Accepts dates, times, and ranges in locale-specific formats.