52 lines
2.6 KiB
Markdown
52 lines
2.6 KiB
Markdown
# Translation files
|
|
|
|
The web app loads translations per locale from this directory. Each `*.json`
|
|
under `<locale>/` corresponds to one i18next namespace.
|
|
|
|
## Layout
|
|
|
|
```
|
|
apps/web/public/locales/
|
|
├── de/
|
|
│ ├── translations.json # Legacy single-file namespace (4000+ keys)
|
|
│ ├── errors.json # HTTP/auth/app error copy
|
|
│ ├── mail.json # Subjects + bodies for transactional emails
|
|
│ ├── common.json # Buttons / generic UI / ICU plurals (#72)
|
|
│ ├── settings.json # Per-area: settings surfaces (#72)
|
|
│ ├── billing.json # Per-area: billing surfaces (#72)
|
|
│ ├── crm.json # Per-area: CRM surfaces (#72)
|
|
│ ├── auth.json # Per-area: authentication surfaces (#72)
|
|
│ └── emailMarketing.json # Per-area: email marketing surfaces (#72)
|
|
├── en/ (same files)
|
|
├── pl/ · ru/ · uk/ · hu/ (same files, individually release-gated)
|
|
└── <locale>-formal/ (all nine files; sparse formal overrides)
|
|
```
|
|
|
|
## Conventions
|
|
|
|
- **Default namespace:** `translations` (legacy). Existing callsites continue
|
|
to work unchanged.
|
|
- **Per-area namespaces:** use the existing namespace that matches the surface:
|
|
`common`, `settings`, `billing`, `crm`, `auth`, or `emailMarketing`. Use the
|
|
registered name exactly; `emailMarketing` is camelCase.
|
|
- **Brand-new namespaces:** create matching `de/` and `en/` JSON files and
|
|
register the namespace in `packages/i18n/src/index.ts#i18nNamespaces`.
|
|
- **Key naming:** dotted scope.action — `locale.title`, `action.save`.
|
|
- **ICU plurals:** wrap the count expression as
|
|
`{count, plural, one {# item} other {# items}}`. The custom
|
|
`useTranslate()` hook detects the ICU shape and routes it through
|
|
`intl-messageformat`; the legacy i18next `_one`/`_other` suffix style stays
|
|
supported for back-compat.
|
|
- **Parity gate:** every catalog-ready base locale has identical keys across all
|
|
nine namespaces. Formal directories contain the same nine files but only
|
|
override copy that differs from their base locale.
|
|
- **Release gate:** a catalog can be checked in while disabled. It becomes
|
|
selectable only through `I18N_ENABLED_LOCALES`, after its review manifest in
|
|
`docs/contributing/i18n/reviews/` is current and the native-speaker sample is
|
|
documented.
|
|
- **Quality gate:** `scripts/i18n-check.ts` enforces parity and
|
|
`scripts/i18n-quality.ts` protects placeholders, ICU arguments, tags, URLs,
|
|
Unicode normalization, plural categories and source hashes.
|
|
|
|
See `docs/contributing/i18n.md` for the long-form guide.
|