---
title: "Localization"
description: "Env-driven locale SSOT, next-intl routing, and translation files (v1.6.0)"
locale: "en"
---
# Localization

Ring Platform v1.6.0 uses **env-driven locale configuration** and **next-intl** with `localePrefix: 'as-needed'`.

## Canonical config

```bash
# .env.local
NEXT_PUBLIC_SUPPORTED_LOCALES=en,uk,ru
NEXT_PUBLIC_DEFAULT_LOCALE=en
```

Source of truth: `lib/locale-config.ts` — imported by routing, SEO, preferences, and static generation.

## Translation files

- Path: `locales/{locale}/**/*.json`
- Loader: `lib/i18n.ts` `buildMessages(locale, scope)`
- Request config: `i18n/request.ts`
- Editor bundle: `locales/{locale}/editor.json`

## Client navigation rules

1. Use `Link`, `useRouter`, `usePathname` from `@/i18n/routing` only.
2. Do **not** regex-strip locale prefixes in client components.
3. Switch locale: `persistRingLocalePreference()` + `replaceLocalePath()` from `lib/locale-pref.ts`.

## SEO

- Hreflang: `components/seo/hreflang-links.tsx`
- Metadata: `lib/seo-metadata.ts` with `pathnameWithoutLocale()` for raw URLs

## Adding a language

1. Add locale code to `NEXT_PUBLIC_SUPPORTED_LOCALES`
2. Create `locales/{code}/` mirror structure
3. Update `meta.json` in docs for UK/RU gap tracking

## Related

- [Locale system feature](/docs/features/locale-system.md)
- [LOCALE-GAPS manifest](/scripts/LOCALE-GAPS.md)