# What language your emails go out in

## Purpose
Explain how the product chooses the language of an invitation, a reminder, an
acceptance letter or a feedback notice, and what you can change to steer it.

## Who this is for
Account administrators and campaign managers running a bilingual programme.

## The short answer

Every message is written in **the recipient's own language when their record states
one**, and otherwise in **English plus your account's primary language**, English
first.

The rule, in order:

1. **The person's own record.** A participant row that states a language wins over
   everything else: the **Language** field on their roster row. So does the stored
   language preference of a member you are inviting, when the invitation is linked to
   an existing identity. They get that language **alone**.
2. **Nobody said anything → English + your primary language.** Your account's primary
   language is **the first language in your account's list** of published languages.
   The message then carries two sections in one email: **English first**, your primary
   language second.
3. **Your primary language is English**: the message is a single English section.
   That is true even if you publish other languages as well.
4. **You publish nothing at all**: English, as before.

So an account whose list reads *French, English* is written to in English **and**
French; one whose list reads *English, French* is written to in English only. **The
order of your list is the whole of what the product knows about your primary
language**: there is no separate field, and the **Primary** control on the languages
screen is what moves a language to the front of it.

### Which languages a message can be written in

All four the product supports: **English, French, Spanish (`es`) and Brazilian
Portuguese (`pt-BR`)**. Spanish and Portuguese joined in September 2026; before that a
Spanish-primary account was written to in English because there was no Spanish copy to
send.

:::note The Spanish and Portuguese wording was reviewed

The Spanish and Brazilian Portuguese sentences were drafted from the English and
French originals and accepted by the owner on 11 September 2026. All four languages are
now on the same footing; a wording change in any of them is an ordinary edit to the
catalogue.

:::

### Setting your primary language

Sidebar **Settings → Preferences** is where you turn languages on and off, and where
you choose which one is primary. Each language has a **Primary** radio beside its
checkbox:

- **Only an enabled language can be primary.** The radio is greyed out until you tick
  the language.
- **Choosing one saves it first.** The screen sends your chosen language at the head of
  the list and the others behind it in the order they were already in, so nothing else
  moves, and the panel heading says which language is currently primary.
- **Turning the primary language off passes it on** to the next enabled language, so
  there is never a primary you have switched off. Turning a new language on adds it at
  the end and leaves your primary alone.
- **Saving is safe to repeat.** An account whose primary is French stays French after
  the next person opens this screen and saves; the screen no longer re-orders anything
  by itself.

Administrators with an integration can still set the order through the account
languages API (`PUT /api/v1/accounts/{accountId}/languages`), which stores the list
exactly as it is sent: the first entry is your primary.

## Setting a person's language

**It is a field on the participant, called Language.** Values are `en`, `fr`, `pt-BR`
and `es`, the four the product supports. Leave it unset and the person is written to
by the rule above; **unset is not the same as English**, and nothing ever fills it in
on somebody's behalf.

Five ways to set it:

- **The roster.** The participants table has a **Language** column. It reads
  "Not stated" for anybody who has not said.
- **The participant dialog.** Adding somebody on the **New user** tab offers
  **Email language**, defaulting to *Not stated*.
- **The engagement tracker.** Opening a person shows **Email language** with a
  selector beside it, the same place you override their consent state. Choosing
  *Not stated* there clears the field and puts them back on the bilingual rule.
- **Import.** A CSV may carry a `language` column (`lang`, `locale`, `emailLanguage`
  and `preferredLanguage` are read as the same column), holding the tag (`en`, `fr`) or
  the language's name (*English*, *Français*). **A spelling the product does not
  recognise never fails the row**: the person is imported with the language
  unstated and the import report says which cell was ignored, in the `notice` column
  of the downloadable CSV.
- **The public API.** `POST /api/v2/public/…/participants` and
  `PATCH /api/v1/…/participants/{id}` both take `language`; sending `null` clears it.
  The read-only contacts export publishes it too.
- **The respondent themselves**, from their own `/me/preferences` page (added
  September 2026). A signed-in respondent may set (or clear) the reading
  language for each programme they hold a roster row in; it writes the same
  field this section describes, so the next reminder or announcement follows
  it exactly as a value you set on the roster would. See
  [What language you see, and how to change it](/use/participants/participant-languages)
  for the respondent-facing side of this control.

A **CRM contact** carries the same field, set from the **Language** selector on the
contact in sidebar **Contacts** (see
[Push people into CRM contacts](/operate/tenant-admin/crm-contacts)).

### If you were using `metadata.lang`

You were, if anybody set this before September 2026: it was the only place the fact
could live. **It still works.** The field is read first and the bag is read after it,
so an integration writing `metadata.lang` is still heard. Existing values were copied
into the field, and any value the product does not recognise was left alone for
somebody to look at rather than guessed at.

### Which languages you may state

The four the product supports, whatever your account currently publishes. Turning
Spanish off on your **Settings → Preferences** does not rewrite what a respondent told
you; it changes which language can be the second half of a two-language message.

## What the link in the message opens in

When a person's own record states a language, every link in their message (the
invitation's **Open invitation** button and their signed assessment links) carries
that language, and the page opens in it.

When it does not, the links carry **no language at all**, deliberately. The page then
chooses for itself, in this order: a language in the address the visitor followed, the
language they last chose on the site, their signed-in preference, their browser's
setting, and finally your account default. Pinning your default onto the link would
overrule a choice the reader had already made.

## What a respondent never sees

Invitations used to print the internal identifiers behind the invitation (a role id, an
account id) and the expiry as a raw UTC timestamp. They do not any more:

- The **role** and the **account** appear by name, or not at all. Where the sending
  path could not resolve a name, the line is omitted rather than filled with an id.
- The **campaign** or **assessment** appears by name, or as "a campaign" / "an
  assessment".
- The **expiry** is written out in the reader's own language, naming UTC.

:::note One call to action for an ordinary participant invite (September 2026)

An invitation onto a roster (the campaign-participant role every self-join and
bulk-import invitee holds) no longer names a **Role:** or **Account:** the way
a staff assignment does: a roster relationship is not a permission grant, and
saying so confused readers. When the invitation already carries the person's
own link to an assessment, **that link becomes the one button** ("Open
`<assessment name>`"), the same verb and the same name the respondent's
landing (`/me/assessments`) uses for its own first card, rather than a
"Set your password and start" button sitting above a second, separate link to
the same place. A genuine staff invitation (an account or campaign manager
role) is unchanged: the activation button stays the call to action, and the
Role:/Account: lines still say what is being granted.

:::

## Related
- [Set a logo and a profile picture](/operate/tenant-admin/branding-and-avatars):
  what your branding does to these messages.
- [Add people to a campaign](/operate/tenant-admin/add-people-to-a-campaign)
- [Translator workflow](/operate/tenant-admin/translator-workflow): translating your
  questionnaires, which is a separate system from the product's own email wording.
