= i18n :description: Write to each user in their own language. The emails of your service, the Stripe Checkout and the Customer Portal follow the language of the user, of the page they are on, or the default you choose. :keywords: i18n, internationalization, multilingual transactional emails, i18n backend, localized verification email, user locale, Stripe Checkout language, localized password reset email, default language :group: Build :order: 47 Your service writes to your users without passing through your app: the emails for verification, password reset, invitations and Stripe orders, and the Stripe pages where they pay. This page says which language each of them is in, and how you choose it. What you get: * **Eight languages, already written.** Our email templates are in English, Italian, Spanish, French, German, Dutch, Portuguese and Polish. * **One language for each user.** A user who chose a language gets every email in it. * **A default you choose.** For the users who chose none, your service has a language of its own. * **Stripe in the same language.** Checkout and the Customer Portal open in the language of the emails. == Which language an email is in The service looks in three places, in this order, and takes the first it finds: . **The user's language.** The `locale` field of the user: their own choice. . **The language of the request.** The `locale` your app sends with the call that makes the email go out: usually the language of the page the user is on. . **The default of your service.** The language you set on the xref:branding.adoc[Branding] page. When none of the three says anything, the email is in English. A `locale` is a language code of 2 to 5 letters in lower case, such as `en` or `it`. A code with a region, such as `it-IT`, is refused with `400`. == The languages of our templates [cols="1,2"] |=== | Code | Language | `en` | English | `it` | Italian | `es` | Spanish | `fr` | French | `de` | German | `nl` | Dutch | `pt` | Portuguese | `pl` | Polish |=== German and French address the reader formally. The others are informal. A user whose language is not in the table gets the email in English. == The default of your service Open **Branding** in the console and choose **Language of the emails**. Click **Save**: it takes effect within a minute. The default is for the users who have no language of their own, when your app names none either. It never changes the language of a user who chose one. == Send the language from your app The xref:kit.adoc[Kit] takes `locale` as the last argument of the calls that send an email. Pass the language your app is showing: [source,typescript] ---- import { register, invite, forgotPassword } from '@ulabase/kit'; // stored on the new user: every later email is in Italian await register(config, { email: 'anna@example.com', password, firstName: 'Anna', lastName: 'Rossi', teamName: 'Acme', locale: 'it', }); await invite(config, 'luca@example.com', 'member', 'it'); await forgotPassword(config, 'anna@example.com', 'it'); ---- What the service does with it depends on the call: [cols="2,3"] |=== | Call | What `locale` does | `register` | Language of the verification email. Stored on the new user. | `invite`, for an email with no account | Language of the invitation. Stored on the user the invitation creates. | `invite`, for an existing user | Language of the invitation, only when the user has none. | `resendInvite`, `forgotPassword` | Language of the email, only when the user has none. |=== These calls never replace the language a user already has. Without the Kit, add `"locale": "it"` to the JSON body of `POST /auth/register`, `/auth/invite`, `/auth/resend-invite` and `/auth/forgot-password`. == Let the user choose A language picker in your app saves the choice with one call: [source,typescript] ---- import { updateProfile } from '@ulabase/kit'; await updateProfile(config, { locale: 'de' }); ---- From then on the user's language comes first, whatever a later request says. Without the Kit it is `PATCH /auth/profile` with `{ "locale": "de" }`. == Stripe: Checkout, the Customer Portal and the order emails Stripe does not tell your service which language a customer reads. Your app does, with the same `locale`: [source,typescript] ---- import { createCheckoutSession, openBillingPortal, createOrder } from '@ulabase/kit'; const { url } = await createCheckoutSession(config, 'gold', 'month', 'it'); const portal = await openBillingPortal(config, 'it'); const order = await createOrder(config, items, { email: 'buyer@example.com', locale: 'it' }); ---- [cols="2,3"] |=== | Call | Language | `createCheckoutSession`, `openBillingPortal` | The `locale` of the call. Without it, the language of the team's billing contact. | `createOrder` | The language of a signed-in buyer who has one. Otherwise the `locale` of the call. It is kept on the order, and the confirmation and refund emails are in it. |=== When nothing names a language, Stripe follows the customer's browser. A language Stripe has no page for is used for the emails only. The emails about a subscription, such as a failed payment or the end of a trial, are in the language of the user who created the team. Without one, they are in the default of your service. == Your own templates A template of yours holds all its languages in one file. Wrap each version of a text in ``: [source,html] ----

Hi {{first-name}}, please verify your address. Ciao {{first-name}}, verifica il tuo indirizzo.

---- The service keeps the version in the language it chose and drops the others. A text outside a `` is in every email. A template with no version in the chosen language falls back to `en`. The subject is the `` of the template and follows the same rule. Where to paste your templates is on the xref:signup-mgmt.adoc#email-templates[Sign-up] page and on the xref:stripe.adoc[Stripe] page. == The sign-in page The sign-in page of the OAuth flow, the one an AI agent opens at `/oauth/login`, is in English whatever the language of your service. It carries your xref:branding.adoc[Branding]: name, color and logo. For a sign-in page in another language, host your own and set its address under *OAuth login page* on the xref:mcp.adoc[MCP] page. == When something goes wrong * **A registration answers `400` since you added `locale`.** The code has a region, such as `en-US`. Send the language alone: `en`. * **A registration answers `400` and names a schema.** The xref:schemas.adoc[schema] of your users collection refuses fields it does not declare. Add `locale` to it as an optional string. * **The email is in English, the user is not.** The user has no `locale`, the request sent none and the service has no default. Set the default on the Branding page. * **The user changed language and the emails did not.** The change went through a call that only guesses, such as `forgotPassword`. Save the user's choice with `updateProfile`. == Related pages * xref:branding.adoc[Branding]: the name, the color, the logo and the default language of your service. * xref:signup-mgmt.adoc[Sign-up, login and invitations]: the three emails of the accounts, and your own templates. * xref:stripe.adoc[Stripe billing]: plans, orders and their emails. * xref:kit.adoc[The Ulabase Kit]: the calls that take `locale`.