feat(i18n): english-only bundle with namespaced, type-checked translation keys

[oliverlaz]

🎯 Goal

Closes REACT-1028.

Two problems with i18n in v14, both fixed here.

The 11 non-English locales shipped whether you used them or not. They were statically imported and copied into Streami18n at construction, so they were un-treeshakeable even for an English-only app — ~112 KB gzip (27% of the bundle), plus 11 dayjs/locale/* side-effect imports and ~150 lines of calendar config.

Translation keys were the English copy. t('Send Message') meant 375 of 706 en.json entries were "X": "X" duplication, any copy edit silently orphaned all 12 translations, and the same word in two contexts couldn't be disambiguated — the codebase had already grown an ad-hoc aria/ prefix to work around exactly that.

v15 is the one window where renaming public translation keys is cheap, so both land together.

🛠 Implementation details

Keys are now stable dotted identifiers, with the English copy inline as i18next's defaultValue:

const { t } = useTranslationContext();

t('message.status.sent.text', 'Sent');

t('channel.memberCount.title', {
  count,
  defaultValue_one: '{{ count }} member',
  defaultValue_other: '{{ count }} members',
});

Namespaces follow the source tree (message.*, messageComposer.*, poll.*), with shared copy under common.* and the modality as the leaf (.label, .ariaLabel, .placeholder, .title, .text). 633 keys across 724 call sites.

Keeping the copy inline is what makes a partial dictionary safe — an unsupplied key still renders English rather than a raw key path — and it means only 71 keys ship as data (timestamp.*, duration.*, language.*, and one postProcessor directive: the ones that can't carry an inline default). The other 562 render from the defaultValue at their call site, removing a further 39,915 raw bytes of duplicated strings.

src/i18n/keys.ts is generated from the call sites and is type-only, so the typed key surface costs nothing at runtime. yarn build-translations regenerates it and hard-fails on a key used with two different copies, a key with no inline default and no bundled entry, or a key defined in both places. CI re-runs it and fails on any diff.

---

Modifying existing copy

Pass overrides for the built-in English. Everything you don't mention is untouched:

import { Streami18n } from 'stream-chat-react';
import type { TranslationDictionary } from 'stream-chat-react';

const i18n = new Streami18n({
  translationsForLanguage: {
    'textareaComposer.textareaPlaceholder.sendMessage.label': 'Write something…',
  } satisfies TranslationDictionary,
});

<Chat client={client} i18nInstance={i18n}>…</Chat>

placeholder      → "Write something…"   (overridden)
common.cancel    → "Cancel"             (untouched, from the inline default)
message timestamp→ "10:30"              (untouched, from runtimeDefaults)

registerTranslation('en', {…}) does the same thing after construction. Every language is layered over the bundled defaults — however you select it, and even with no dictionary at all — so overriding one string can't knock out timestamps.

Catching unknown keys at compile time

Key names are checked against the catalog, so a typo or a leftover v14 key is a compile error:

const good: TranslationDictionary = { 'common.cancel.label': 'Dismiss' };

const typo: TranslationDictionary = { 'common.cancel.lable': 'Dismiss' };
//                                          ^ TS2353 — not a key in the catalog

const stale: TranslationDictionary = { Cancel: 'Dismiss' };
//                                           ^ TS2353 — v14 key, no longer exists

(TypeScript reports the first unknown property per object literal, so fix them one at a time.)

No annotation needed — the parameters are typed, so a dictionary written straight into the call is checked too:

i18n.registerTranslation('de', { 'common.cancel.lable': 'Abbrechen' });
//                                ^ TS2353 — not a key in the catalog

This matters because the failure is otherwise silent: a key that doesn't match simply never applies, and you get English with no error.

Which type to use:

	plural _one/_other	extra categories (_few, _many, _zero)	plural suffix on a non-plural key	stale v14 key	your own keys
TranslationDictionary	✅	✅	❌ rejected	❌ rejected	❌ rejected
LooseTranslationDictionary	✅	✅	⚠️ permitted	⚠️ permitted	✅

registerTranslation() and translationsForLanguage take the strict TranslationDictionary, so a key written inline is checked — that is where a typo used to slip through. LooseTranslationDictionary is the escape hatch for keys the SDK does not define; annotate the variable you pass to opt into it, at the cost of not catching a stale key.

Reaching for it is rarely necessary: TranslationDictionary accepts any category Intl.PluralRules can select, so Russian or Arabic can supply _few / _many / _zero and stay fully checked.

TranslationKey is the union t() accepts; use it to type a t parameter. It is not the right key type for a dictionary, because plural entries live in the catalog as _one/_other while t() takes the bare handle.

Discovering keys: TranslationKey autocompletes in any editor, TranslationCatalog maps each key to its English copy (hover to see what a key renders, or index it — TranslationCatalog['common.cancel.label'] is 'Cancel'), and yarn i18n:export writes the 619 translatable keys as JSON for a translator or TMS. The 14 formatter expressions are left out — a TMS that localises {{value, notification}} breaks notifications — with --all for the full catalog.

Registering a new language

import { Streami18n } from 'stream-chat-react';
import type { TranslationDictionary } from 'stream-chat-react';
import 'dayjs/locale/de.js';

const de: TranslationDictionary = {
  'common.cancel.label': 'Abbrechen',
  'channelDetail.channelMembersView.members.title_one': '{{ count }} Mitglied',
  'channelDetail.channelMembersView.members.title_other': '{{ count }} Mitglieder',
};

const i18n = new Streami18n({
  language: 'de',
  dayjsLocaleConfigForLanguage: {
    calendar: { sameDay: '[heute um] LT', lastDay: '[gestern um] LT' /* … */ },
  },
});

i18n.registerTranslation('de', de);

common.cancel.label  → "Abbrechen"
members.title, n=1   → "1 Mitglied"      ← Intl.PluralRules picks the form
members.title, n=4   → "4 Mitglieder"
common.back.label    → "Back"            ← not supplied, falls back to English
message timestamp    → "10:30"           ← inherited from runtimeDefaults

Plurals are stored as _one / _other; supply whichever categories your language needs and i18next selects between them, so Russian or Arabic can add _few, _many, _zero — all of them type-checked.

Date formats are the one thing you must supply yourself now, and it takes two steps.

1. Only the en dayjs locale is bundled, so import your locale and pass dayjsLocaleConfigForLanguage (including its calendar block), or pass your own preconfigured DateTimeParser. That covers month and weekday names, the plain formats, and the keys that format against the locale's own calendar.

2. Override the four timestamp.* keys that pass their own calendarFormats: DateSeparator, ReminderNotification, ChannelPreviewTimestamp, ChannelDetailPinnedMessageTimestamp. dayjs takes the calendar wording as part of the format string, so these carry English day words — and a per-key calendarFormats replaces the locale's calendar wholesale, so step 1 never reaches them. Skip this and a fully configured German app still renders "Today" in its date separators. Date and time has the copy-pasteable German version.

---

Migration

Every v14 key maps to exactly one v15 key. The full 603-row table is ai-docs/i18n-v15-key-map.json; the integrator-facing guide is ai-docs/i18n-v15-migration.md. Nothing to do if you use the SDK in English and never touched i18n.

A later release adding a key will not break a custom dictionary — TranslationDictionary is Partial, so the new string renders its inline English until it is translated. Keeping a language up to date shows how to turn that into a compile-time diff of what is still untranslated, and a CI gate for completeness.

Also removed: the deTranslations … trTranslations exports, and the misspelled geti18Instance() accessor (use the public i18nInstance field).

Bundled along the way: i18next 25 → 26. None of its breaking changes apply to us — we never used interpolation.format (formatters already go through services.formatter.add), initImmediate, or i18next.format. One undocumented v26 change worth knowing: an undefined interpolation value now short-circuits before the formatter runs. No effect on the SDK, but a custom formatter that produced output from an undefined value will stop being called.

🎨 UI Changes

None. Every rendered string is byte-identical — the English copy moved from en.json into an inline defaultValue at the same call site. The existing suite is the evidence: ~808 assertions on rendered English text, all passing unchanged.

Verification

• yarn test — 2789 passed, 227 files
• tsc -p tsconfig.lib.json --noEmit — clean
• yarn types:scripts — clean
• yarn lint — clean
• yarn validate-translations — clean (regenerates keys.ts byte-identically)
• examples/vite and examples/tutorial — tsc clean

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d8dc29ca-0ffa-43dc-bd44-dc2347917d25

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 75.72115% with 101 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (release-v15@59b7636). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...8n/TranslationBuilder/notifications/translators.ts	14.81%	23 Missing ⚠️
src/components/Message/hooks/usePinHandler.ts	0.00%	8 Missing ⚠️
...omponents/MessageComposer/QuotedMessagePreview.tsx	38.46%	8 Missing ⚠️
src/components/ChannelListItem/utils.tsx	61.11%	7 Missing ⚠️
...ponents/MessageActions/MessageActions.defaults.tsx	73.07%	7 Missing ⚠️
...Accessibility/hooks/useInteractionAnnouncements.ts	81.48%	5 Missing ⚠️
...r/AttachmentPreviewList/AudioAttachmentPreview.tsx	20.00%	4 Missing ⚠️
...ssibility/hooks/useIncomingMessageAnnouncements.ts	50.00%	3 Missing ⚠️
...hannelHeader/hooks/useChannelHeaderOnlineStatus.ts	25.00%	3 Missing ⚠️
...components/Message/MessageTranslationIndicator.tsx	57.14%	3 Missing ⚠️
... and 21 more

Additional details and impacted files

@@              Coverage Diff               @@
##             release-v15    #3261   +/-   ##
==============================================
  Coverage               ?   84.22%           
==============================================
  Files                  ?      525           
  Lines                  ?    15989           
  Branches               ?     5114           
==============================================
  Hits                   ?    13467           
  Misses                 ?     2522           
  Partials               ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[MartinCupela]

@oliverlaz I think it would provide value to integrators if we included at least one other language mutation in the examples/vite app one. That way it will be easier to understand what steps are necessary to add own mutations. WDYT?

[oliverlaz]

@oliverlaz I think it would provide value to integrators if we included at least one other language mutation in the examples/vite app one. That way it will be easier to understand what steps are necessary to add own mutations. WDYT?

Sure thing! I'll extend the demo and adjust the docs too. But first I wanted to get some feedback on the implementation before moving to the other parts.

[MartinCupela]

Does it make sense to add castings as unknown as?