Progmasoft Git

progmaweb

The site and account service of Progmasoft: a Next.js frontend and an ASP.NET Core API.

Clonegit clone https://git.progmasoft.com/progmaweb

mainroot / docs / LOCALIZATION.md

4.3 KiB · Raw · Log

<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

# Localization

Every page of Progmaweb is published in four languages. All of them live in `apps/web/lib/localization.ts`.

| Locale | Language |
| --- | --- |
| `en-US` | English |
| `de-DE` | German |
| `ru-RU` | Russian |
| `fr-FR` | French |

Hebrew (`he-IL`) was published until 2026-11-18 and is retired. A link that still asks for it with `?lang=he-IL` is
redirected for good (308) to the address without the parameter, and the cookie is set to `en-US`. A browser that
prefers Hebrew gets the fallback.

A page has one URL in every language. There are no language-specific paths and no `hreflang` alternatives, because a
language is a preference of the visitor, not a second address of the page.

## How a page picks its language

For each request the server decides in this order (`apps/web/lib/locale.server.ts`):

1. **The visitor's choice.** A valid `progmasoft_locale` cookie always wins.
2. **The browser.** Without that cookie the `Accept-Language` header is negotiated: the published language with the
   highest quality wins, and the order of the header breaks ties. Only the primary language is compared, so `de-AT`
   selects German.
3. **The fallback.** A browser that prefers no published language gets `en-US`.

Examples of the negotiation:

| `Accept-Language` | Page language |
| --- | --- |
| `fr-CA,fr;q=0.9,en;q=0.8` | French |
| `de-AT,de;q=0.9` | German |
| `tr-TR,tr;q=0.9,de;q=0.5` | German, the first preference that is published |
| `tr-TR,tr;q=0.9` | English, the fallback |
| `en;q=0.3,ru;q=0.9` | Russian; quality decides, not position |
| absent | English |

The header comes from the browser and is not trusted: only its first 1024 characters are read, and a malformed or
zero quality never selects a language.

## How a visitor changes the language

The language menu in the header calls the server action `selectLocale` (`apps/web/lib/locale.actions.ts`). The action
stores the cookie, and Next.js renders the current route again and applies the result in place. Nothing is reloaded:
scroll position, theme and form input stay as they are.

A link can carry the same choice as `?lang=<locale>`. The proxy stores the cookie and redirects to the URL without the
parameter, so a preference never becomes a second indexed address. The menu falls back to this link when the action
cannot reach the server.

A value that is not a published locale is ignored in both paths.

## The language cookie

| Attribute | Value |
| --- | --- |
| Name | `progmasoft_locale` |
| Domain | `.progmasoft.com` on production hosts, so the choice follows the visitor to the other Progmasoft hosts; host-only elsewhere |
| Lifetime | one year |
| Flags | `HttpOnly`, `SameSite=Lax`, and `Secure` over TLS |

Both paths write the cookie through `localeCookieOptions`. Two writers with different attributes would leave two
cookies behind, one shadowing the other.

## Message tree

`messages` holds one tree per locale with identical shape. Pages and components read it through
`getMessages(locale)`; there is no lookup by string key and no fallback from one language to another, so a missing
message is a type error or a failing test rather than an English sentence on a German page.

The tests in `apps/web/tests/localization.test.mjs` enforce that

- every locale has exactly the keys and array lengths of `en-US`, with no empty string;
- every locale has a name in its own language for the menu;
- negotiation and cookie attributes behave as described above.

## Adding a language

1. Add the locale to `supportedLocales`, its own name to `localeNames`, and its primary language to
   `localeByLanguage`.
2. Every published language is written left to right. A language written right to left needs rules for the direction
   of its text first.
3. Add a complete message tree. Copy the `en-US` tree and translate every string; keep product names and technical
   identifiers such as `BUILD.kts` unchanged.
4. Extend the tests: the list of published locales and a negotiation case for the new language.
5. Run `pnpm check`, `pnpm test`, `pnpm lint` and `pnpm build`, then read every page in the new language in a
   browser, in both themes and at a narrow width.

Have a native speaker read the text before it is published. The French text has not had that review yet; see
[Known limitations](LIMITATIONS.md).