---
id: portfolio.ds.localizable-copy-rule
name: "Localizable Copy Rule"
type: rule
status: active
relations: [{"type":"related_to","target":"portfolio.ds.header"},{"type":"related_to","target":"portfolio.ds.language-switcher"},{"type":"related_to","target":"portfolio.ds.locale-fallback-notice"},{"type":"related_to","target":"portfolio.ds.page-template"},{"type":"related_to","target":"portfolio.ds.prop-naming-rule"}]
sources: ["apps/portfolio-site/src/design-system/docs/localizable-copy-rule.astro","apps/portfolio-site/src/i18n/messages.ts","apps/portfolio-site/src/lib/designSystemRegistry.ts","packages/design-system/src/components/GenericPageTemplate.astro"]
catalog: ["apps/portfolio-site/src/design-system/docs/localizable-copy-rule.astro"]
previews: ["apps/portfolio-site/src/design-system/docs/localizable-copy-rule.astro"]
---
# Localizable Copy Rule

## Purpose

Keep reusable Design System components language-independent while ensuring that all user-facing text can be localized coherently.

## Hook

Use when creating a content-bearing component, adding visible or accessible copy, formatting locale-sensitive values, or wiring a component into a localized page.

## Contract

- Reusable components expose visible copy and accessibility text through named props or a component-scoped `Labels` object.
- Prop names describe semantic purpose, not language-specific wording.
- English defaults are allowed for isolated Design System previews and backward-compatible component use.
- Production page compositions pass all copy from one coherent locale dictionary.
- Dynamic client-state messages, live-region feedback, tooltips, empty states, date labels, and action labels follow the same boundary as static copy.
- The Design System package must not import application dictionaries or own translation snapshots.
- Locale dictionaries, localized routes, translation freshness, fallback selection, canonical links, `hreflang`, `inLanguage`, and document language remain application responsibilities.
- A missing or stale translation renders through the application fallback contract; components do not infer or machine-translate text.
- New components must follow this rule from their first implementation.
- Existing components must be brought into compliance whenever localization touches them.

## Use

- Adding a heading, description, button label, status, accessible name, or live-region message to a component.
- Passing translated page copy into a Design System composition.
- Formatting dates or grouped content using an application-provided locale.

## Do Not Use

- Do not import `apps/portfolio-site/src/i18n` from `packages/design-system`.
- Do not duplicate a component for English, Russian, or Latvian.
- Do not publish unreviewed or stale translated copy as current content.
- Do not use CSS-generated text for meaningful interface copy.

## Edge Cases

- Route-independent components may use English preview defaults, but every production string must remain overrideable.
- When fallback English is rendered on a localized route, the application keeps requested-locale navigation while declaring English as the content language.
- Localized strings can expand significantly; text containers must wrap without clipping, overlap, or horizontal overflow.
- When a client script changes text after interaction, pass every possible state string through data attributes or another explicit component prop boundary.

## Accessibility

- Accessible names, live-region feedback, and tooltip actions must be localized with their visible context.
- The document `lang` value must describe the content actually rendered.
- Language links expose destination language through `lang` and `hreflang`.

## Related Components And Patterns

- `Page Template`: receives locale-aware labels and passes them into the shared shell.
- `Header`: receives navigation and accessibility copy without importing dictionaries.
- `Language Switcher`: renders application-provided locale destinations.
- `Locale Fallback Notice`: presents the application fallback decision.
- `Prop Naming Rule`: defines canonical `Locale` and `Labels` prop names.

## Code Paths

- `apps/portfolio-site/src/i18n/messages.ts`
- `apps/portfolio-site/src/design-system/docs/localizable-copy-rule.astro`
- `packages/design-system/src/components/GenericPageTemplate.astro`

## Verification

- Verify visible, accessible, and dynamic text boundaries for every component changed by localization.
- Test Mobile, Tablet, Desktop, and Ultra-wide layouts with longer Russian and Latvian strings.
- Run `npm run check:localization`.
- Run `scripts/design-system-graph --check --no-write`.