Ulabase

Build

i18n

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.

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:

  1. The user’s language. The locale field of the user: their own choice.

  2. 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.

  3. The default of your service. The language you set on the 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

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 Kit takes locale as the last argument of the calls that send an email. Pass the language your app is showing:

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:

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:

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:

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' });
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 <span lang="…">:

<p>
  <span lang="en">Hi {{first-name}}, please verify your address.</span>
  <span lang="it">Ciao {{first-name}}, verifica il tuo indirizzo.</span>
</p>

The service keeps the version in the language it chose and drops the others. A text outside a <span lang> is in every email. A template with no version in the chosen language falls back to en.

The subject is the <title> of the template and follows the same rule. Where to paste your templates is on the Sign-up page and on the 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 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 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 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.