Translate Pinchana Web

Pinchana Web translations are ordinary JSON files reviewed through GitHub pull requests. No external translation account/service is required.

Current active interface locales are:

• English (en) — default/source language
• Ukrainian (uk)

Both English and Ukrainian are currently approved for legal pages as well.

Catalogs

• messages/app — interface text, accessibility labels, notifications, metadata, settings, and Web-owned API messages.
• messages/legal — Privacy Policy and Terms of Use.
• messages/app/en.json — authoritative English application catalog.

Each translatable entry keeps the English source next to its translation:

{
  "language": {
    "pickerLabel": {
      "source": "Change language",
      "translation": "Змінити мову"
    }
  }
}

For an existing translated locale, edit translation only unless the authoritative English message itself is intentionally changing. Keep the JSON key and source value synchronized with English so tests can detect stale translations.

Translate an existing locale

1. Fork Pinchana/pinchana-web.
2. Edit the target messages/app/<locale>.json or messages/legal/<locale>.json file.
3. Preserve ICU variables/select/plural syntax and rich-text tags such as <link>...</link> exactly.
4. Keep product names, codecs, cookie identifiers, URLs, filenames, revision hashes, and raw upstream errors unmodified when they are identifiers rather than prose.
5. Run the repository checks.
6. Open a PR explaining the locale and catalog you changed.

Add a new locale

Copy the relevant English catalog to a BCP 47 locale filename, keep every source field unchanged, and translate the translation values.

An incomplete catalog can be reviewed incrementally, but maintainers do not add it to the active picker until the application catalog and runtime registration are ready.

Runtime locale registration lives in i18n/config.ts. A new active language needs its code, native label, text direction, and flag added to SUPPORTED_LOCALES, plus the repository’s static catalog loading path.

Legal translations

Legal activation is deliberately separate from UI activation. English legal text remains the authoritative baseline. A legal locale is shown only after maintainers add it to APPROVED_LEGAL_LOCALES following the required accuracy review.

A new UI language can therefore be active while legal pages temporarily fall back to English with the appropriate notice.

Validate locally

git clone https://github.com/Pinchana/pinchana-web.git
cd pinchana-web
bun install --frozen-lockfile
bun run test
bun run lint
bun run build

Catalog tests should catch missing active messages, blank translations, modified source strings, invalid ICU syntax, and mismatched variables/rich-text tags. A production build catches integration/type/build issues before merge.

Locale behavior

Pinchana Web does not use locale-prefixed URLs. Server-side locale selection uses the pinchana_locale cookie first and Accept-Language second, with English as the fallback.

The language picker updates that cookie so server-rendered and client-rendered messages stay consistent.