Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

9.2 KB
Raw Blame

Languages

The account preference is the durable interface language. The server render reads its local copy from a cookie one time for each request. Without that cookie, it uses the first supported language in the browser's Accept-Language header. English is the fallback when the header contains no supported language. After sign-in, the account preference replaces a different rendered language.

The message files

apps/web/messages/<locale>/<namespace>.json. There is one file for each top-level namespace, and the same set of files for each language. A namespace is a domain (issue, members, settings), not a page. Thus a screen that contains parts of more than one feature reads more than one namespace.

English is the source language. src/i18n/messages.ts imports all the English files statically. The messages of the selected language then replace the English text, key by key. A key with no translation keeps its English text and does not show the key path.

TypeScript uses the same imports for the type Messages in global.d.ts. That type gives the permitted keys for t('…'). loadMessages imports the other languages dynamically, one namespace at a time.

Where the code is

File Content
apps/web/messages/<locale>/*.json the messages, one file for each namespace
apps/web/src/i18n/messages.ts the English imports, loadMessages, the English fallback
apps/web/src/i18n/request.ts reads the cookie and gives the messages to next-intl
apps/web/src/i18n/accept-language.ts matches the browser language to a supported language
apps/web/src/i18n/locales.ts the language list, the labels, the flags, isLocale
apps/web/src/i18n/cookie.ts writes NEXT_LOCALE
apps/web/global.d.ts types each key against the English files
apps/web/src/components/preferences-sync.tsx writes the cookie from the account preference, and refreshes
apps/web/src/components/locale-toggle.tsx the language switcher
apps/web/src/hooks/useDateFnsLocale.ts the month names and the weekday names of the calendar
apps/api/src/modules/user-preferences/ the stored preference and its validation

How to add a key

Add the key to messages/en/<namespace>.json first. Then add it to the other languages. The English file gives the type. Thus a t('…') for a key that is not in that file causes a typecheck error. A key that is absent from a translated file shows in English at runtime, and bun run lint fails it. So does a key that is present only in a translated file.

How to add a namespace

Make the file in each language directory. Then add the namespace to coreMessages in src/i18n/messages.ts. No code finds the file automatically.

How to add a language

There are five locations, and no migration is necessary.

  1. Copy messages/en/ to apps/web/messages/<code>/ and translate the files. Keep every key: bun run lint fails a file with a missing or an extra key. A value left in English is permitted.
  2. Add the code to LOCALES in apps/web/src/i18n/locales.ts. Add the name of the language, in that language, to LOCALE_LABELS. Add a flag to LOCALE_FLAGS. TypeScript types both records by locale, thus an absent entry causes a typecheck error.
  3. Add the applicable import from date-fns/locale to apps/web/src/hooks/useDateFnsLocale.ts. If you do not, the month names and the weekday names of the calendar stay in English, and no error occurs.
  4. Add the code to LOCALES in packages/mailer/src/locale.ts. If you do not, the API refuses the new code, and the switcher cannot save it.
  5. Add the emails of the language: a file in packages/mailer/src/templates/texts/, listed in LOCALE_TEXTS in catalog.ts. TypeScript types that record by locale, thus an absent entry causes a typecheck error.

A language written right to left is also added to RTL_LOCALES in locales.ts and in packages/mailer/src/locale.ts. See below.

The user_preference.locale column is a plain text column with no CHECK, so the set of languages can increase with no change to the schema.

Direction

localeDirection in src/i18n/locales.ts gives the writing direction of a language, from the RTL_LOCALES list. Three places read it:

  • app/layout.tsx puts it on <html dir> during the server render, so the first paint is already mirrored and the layout does not flip after hydration.
  • providers.tsx gives it to Radix's Direction.Provider. Radix reads the direction from that context rather than from the CSS, and it is what makes a menu's arrow keys and its alignment follow the language.
  • The same value picks the corner the toasts appear in.

Most of the interface mirrors from those alone: Radix moves its own primitives, and the flex and grid layouts follow the document direction.

What does not mirror is a component that positions itself with a physical CSS property. Tailwind's ml-, pl-, left-, text-left and border-l compile to margin-left, text-align: left and so on, and those ignore dir. Use the logical utilities in new code — ms/me, ps/pe, start/end, border-s/border-e, text-start/text-end — and fix an existing one when a page is found to read wrongly, rather than converting them ahead of time.

Two shapes are worth knowing before changing any of them:

  • A centring pair. left-1/2 with translate-x-[-50%] centres an element. translate-x has no logical form, so making only the offset logical pushes the element off screen. Keep both physical, or add an rtl: counterpart for the transform.
  • An edge the caller names. Sheet's side="right" is a physical choice, and its slide-in animation is physical too. Both stay that way.

The shadcn primitives in src/components/ui/ are generated, so none of this is fixed by editing them — bunx shadcn add would overwrite it. They are corrected from the outside instead:

  • A rule in globals.css keyed to the primitive's data-slot attribute, which shadcn ships for this purpose. That is how the dialog and sheet close buttons move to the end edge, how the Switch thumb travels towards the end of its track, and how the sidebar's inset margin and trigger icon follow the direction. These rules sit outside @layer, because Tailwind orders its layers theme, base, components, utilities and a rule in @layer components loses to the utility classes on the element however specific it is.
  • A prop the component already exposes, when there is one. Sidebar takes side, so the two callers pass useSidebarSide() and the sidebar sits on the edge the reader starts from.

Content that is not prose keeps its direction through a dir="ltr" container: the timelines place their bars in pixels from the left edge and time runs one way in every language, Recharts draws to absolute SVG coordinates, code and JSON are never right to left, and react-grid-layout has no right-to-left mode. Everything inside such a container then behaves as left-to-right without further edits. This one cannot come from CSS — Tailwind's rtl: variant keys off the dir attribute, so the attribute itself has to be on the element. For a chart that means the ChartContainer call sites pass dir="ltr", rather than the primitive setting it.

Text a user wrote gets dir="auto" instead of the interface direction, so an Arabic comment in an English session — and the reverse — is laid out by its own script. That covers the markdown renderer, both editors, issue titles and the comment box.

Known gap: dnd-kit's horizontalListSortingStrategy computes displacement from index order, so while a horizontal tab strip is dragged its neighbours slide the wrong way. The drop lands correctly, because closestCenter is geometric.

Dates and relative times

next-intl formats the dates, the numbers, and the relative times for the active locale. request.ts also sets now one time for each request. The server render and the client use that same value. Thus "3 hours ago" does not come from two different clocks, and the markup agrees at hydration.

The calendar makes its own month names and weekday names with date-fns. useDateFnsLocale gives the applicable date-fns locale. For a locale that is not in its map, it gives enUS.

Rejected alternatives

One file for each namespace. The alternative is one file for each language, with all the namespaces in it. In that file each change conflicts with the other changes, and you must scroll to find a key.

All the messages go to the client. NextIntlClientProvider receives the full set. If you send only some namespaces with pick(), you save approximately 100 KB of raw JSON for each page. But a namespace that is absent from that list then causes a failure at runtime, in the component that needs it, and not at typecheck. The next-intl maintainer does not recommend this at this size.