⭐️⭐️⭐️ 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.
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.
- Copy
messages/en/toapps/web/messages/<code>/and translate the files. Keep every key:bun run lintfails a file with a missing or an extra key. A value left in English is permitted. - Add the code to
LOCALESinapps/web/src/i18n/locales.ts. Add the name of the language, in that language, toLOCALE_LABELS. Add a flag toLOCALE_FLAGS. TypeScript types both records by locale, thus an absent entry causes a typecheck error. - Add the applicable import from
date-fns/localetoapps/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. - Add the code to
LOCALESinpackages/mailer/src/locale.ts. If you do not, the API refuses the new code, and the switcher cannot save it. - Add the emails of the language: a file in
packages/mailer/src/templates/texts/, listed inLOCALE_TEXTSincatalog.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.tsxputs it on<html dir>during the server render, so the first paint is already mirrored and the layout does not flip after hydration.providers.tsxgives it to Radix'sDirection.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/2withtranslate-x-[-50%]centres an element.translate-xhas no logical form, so making only the offset logical pushes the element off screen. Keep both physical, or add anrtl:counterpart for the transform. - An edge the caller names.
Sheet'sside="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.csskeyed to the primitive'sdata-slotattribute, which shadcn ships for this purpose. That is how the dialog and sheet close buttons move to the end edge, how theSwitchthumb 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 layerstheme, base, components, utilitiesand a rule in@layer componentsloses to the utility classes on the element however specific it is. - A prop the component already exposes, when there is one.
Sidebartakesside, so the two callers passuseSidebarSide()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.