i18n on the server

The backend translates very little. Most text a user sees is rendered by the web app or the mobile app from their own translation files. The server owns text in a few specific places, and each has its own way of choosing a language.

What is translated where

Text	Language source	Mechanism
Transactional emails	`NEXT_LOCALE` cookie, the user’s stored `locale`, or the studio’s `locale`	`@repo/i18n` translation files, `mail` scope
Trainee push notifications	The studio’s own configured text	Templates stored per studio, Hebrew defaults in code
API error messages on `/v1`	Not translated	English strings, clients branch on `code` and `details.reason`
Public signing lane errors	Hebrew, fixed	String literals in `modules/form-sign/`
Automation API errors	English sentences	Written to be shown to a coach as is
AI assistant, WhatsApp agent, plan import prompts and replies	Hebrew	Prompts and canned replies in the module
Exercise and food catalog text	Hebrew data	Imported data files and library rows

`@repo/i18n`

packages/i18n holds the locale config and the translation files that the server needs.

export const config = {
  locales: {
    he: { label: 'עברית', currency: 'ILS', dir: 'rtl' },
    en: { label: 'English', currency: 'USD', dir: 'ltr' },
    ar: { label: 'العربية', currency: 'ILS', dir: 'rtl' },
    de: { label: 'Deutsch', currency: 'USD', dir: 'ltr' },
    es: { label: 'Español', currency: 'USD', dir: 'ltr' },
    fr: { label: 'Français', currency: 'USD', dir: 'ltr' },
  },
  defaultLocale: 'he',
  defaultCurrency: 'USD',
  localeCookieName: 'NEXT_LOCALE',
} as const;

Export	Purpose
`config`	Locales, default locale, cookie name.
`Locale`	Union of the locale keys.
`getLocaleDirection(locale)`	`rtl` or `ltr`.
`getMessagesForLocale(locale, scope)`	Loads and merges translation JSON. `scope` is `saas` or `mail`.
`defaultMailTranslations`	The English `mail.json`, used for typing.
Types	`MailMessages`, `SaasMessages`, `SharedMessages`, `TextDirection`

Six locales are supported: he, en, ar, de, es, fr. Hebrew and Arabic are right to left.

Translation files

packages/i18n/src/translations/<locale>/
├── mail.json     email templates
├── saas.json     web app strings
└── shared.json   strings shared by both

saas.json is in this package because the package was ported from the web app. The server reads the mail scope. The web app has its own copy of these files in its own repo.

How messages are loaded

getMessagesForLocale(locale, scope):

Reads <locale>/<scope>.json and <locale>/shared.json from disk and merges them.
If the locale is not the default, loads the same two files for the default locale (he) and merges the requested locale on top.

So a key missing from a non default locale falls back to Hebrew, not English. A missing file is treated as an empty object. Files are read with fs relative to the compiled module (import.meta.url). A dynamic import() of JSON did not survive bundling. The build script copies the files:

"build": "tsup && rm -rf dist/translations && cp -R src/translations dist/translations"

After editing a translation file, rebuild @repo/i18n, or the running API keeps the old text.

How locale is resolved

There is no locale middleware on /v1. The domain API does not read Accept-Language or any locale header.

Context	Source
better-auth emails	`getLocaleFromRequest` in `auth.ts` parses the `NEXT_LOCALE` cookie from the request. Missing cookie gives the default, `he`.
oRPC procedures that need it	`localeMiddleware` in `@repo/api` reads the same cookie and adds `locale` to the procedure context. Used by `createCheckoutLink` and `createCustomerPortalLink`.
Coach notification emails	`User.locale` on the auth user.
Team invitation email	`Studio.locale`, when it is one of the six mail locales.
Push notifications	No locale. The studio’s stored template text is sent as written.

Studio.locale defaults to he and Studio.timezone to Asia/Jerusalem in the schema. User.locale is optional.

Push notification text

Push text is configuration, not translation. Each studio edits its own titles and bodies in the notification settings, and those strings are stored in StudioNotificationConfig. The fallbacks in NOTIFICATION_CONFIG_DEFAULTS are written in Hebrew. A studio that works in another language changes the text in settings. There is no per trainee language for push.

Hebrew in code

Several modules contain Hebrew string literals on purpose:

modules/form-sign/: every error the signing page shows.
modules/assistant/ and modules/agent/: system prompts, canned replies, cap and error messages.
modules/plan-import/ocr.ts and the structurers: prompts.
ai/nutrition-analyzer.ts: the prompt is English but instructs the model to answer with Hebrew names and notes.
modules/trainee/trainee.service.ts: the display name for a deleted trainee.
modules/foods/food-enums.ts: household measure and unit labels.
Sorting by name uses localeCompare(other, 'he') in a few list builders.

These are product decisions for a Hebrew first market, not missing translations. Do not route them through @repo/i18n without a reason, because that package is consumed from dist and the strings would be far from the code that depends on their exact wording (tests pin some of them).

Catalog data

Exercise names, instructions and food names are data. The Hebrew exercise catalog and instructions are imported from files under apps/core-api/src/scripts/data/ by the import scripts. Localized display of that data is handled by the clients.

Rules for new server text

An error on /v1: write a short English message for developers and logs. If a client must react to it, add a stable details.reason. The client translates.
An error a coach reads directly (automation API, MCP): write a full English sentence that says what to fix.
An email: add a template and keys in mail.json for all six locales. See Mail.
A push: add a notification type with default text and let studios edit it. See Notifications and push.
Never build a user facing sentence by concatenating translated fragments. Hebrew and Arabic word order and direction break it.
Direction: any server rendered document (email, PDF) must set direction from getLocaleDirection. The signed PDF renderer has its own bidirectional text handling in modules/form-sign/visual-text.ts.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

i18n on the server

What is translated where

`@repo/i18n`

Translation files

How messages are loaded

How locale is resolved

Push notification text

Hebrew in code

Catalog data

Rules for new server text

​What is translated where

​@repo/i18n

​Translation files

​How messages are loaded

​How locale is resolved

​Push notification text

​Hebrew in code

​Catalog data

​Rules for new server text

What is translated where

`@repo/i18n`

Translation files

How messages are loaded

How locale is resolved

Push notification text

Hebrew in code

Catalog data

Rules for new server text