@stream-io/video-react-sdk 1.43.2 → 2.0.0-beta.1

package/src/i18n/Streami18n.ts

@@ -0,0 +1,67 @@
+import { Streami18n as CoreStreami18n } from '@stream-io/i18n';
+import type { Streami18nOptions as CoreStreami18nOptions } from '@stream-io/i18n';
+
+import { runtimeDefaults } from './runtimeDefaults';
+import type { BundledKey, TranslationCatalog } from './types';
+
+/**
+ * Options for {@link Streami18n}.
+ *
+ * Core's options, narrowed to this SDK's catalog so `translationsForLanguage` is key-checked.
+ * `runtimeDefaults` is *merged* over the SDK's own rather than replacing it, so supplying it adds to
+ * what the SDK ships.
+ */
+export type Streami18nOptions = CoreStreami18nOptions<TranslationCatalog>;
+
+/**
+ * Wrapper around [i18next](https://www.i18next.com/) for this SDK's translations. Pass an instance
+ * to `<StreamVideo i18nInstance={…}>` to control the language and the copy.
+ *
+ * The implementation lives in `@stream-io/i18n`, shared with the React Native SDK and with Chat.
+ * What this subclass adds is what is this package's own: its bundled translation data, and the two
+ * type parameters — core cannot supply either, because the key catalog is generated from *this*
+ * package's `t()` call sites.
+ *
+ * ## Overriding some of the English copy
+ *
+ * ```ts
+ * const i18n = new Streami18n({
+ *   translationsForLanguage: {
+ *     'common.participants.label': 'People',
+ *   },
+ * });
+ * ```
+ *
+ * ## Adding a language
+ *
+ * ```ts
+ * import 'dayjs/locale/nl';
+ *
+ * const i18n = new Streami18n({ language: 'nl' });
+ * i18n.registerTranslation('nl', {
+ *   'callControls.cancelCallButton.leaveCall.title': 'Verlaten',
+ * });
+ * ```
+ *
+ * No dayjs locale file defines `calendar` — that field belongs to the calendar plugin — so a
+ * language whose relative dates must read natively needs the locale import *and* a `calendar`
+ * config passed as the third argument.
+ *
+ * Type your dictionary as `TranslationDictionary` to turn a typo or a key removed in a later major
+ * into a compile error. A **partial dictionary is safe**: any key you leave out renders the English
+ * copy that ships inline at each call site, never a raw dotted path — so there is no need to
+ * translate everything before shipping a language.
+ *
+ * Reactivity goes through `i18n.state`, a `StateStore`. `setLanguage()` returns nothing — the new
+ * `t` is published to that store, which the provider subscribes to.
+ */
+export class Streami18n extends CoreStreami18n<TranslationCatalog, BundledKey> {
+  constructor(options: Streami18nOptions = {}) {
+    super({
+      ...options,
+      // Merged, not replaced. Spreading `options` over a literal would let an integrator supplying
+      // one entry silently drop the SDK's own bundled data, which then renders as raw keys.
+      runtimeDefaults: { ...runtimeDefaults, ...options.runtimeDefaults },
+    });
+  }
+}

package/src/i18n/TranslationContext.tsx

@@ -0,0 +1,55 @@
+import {
+  createDefaultTranslatorFunction,
+  defaultDateTimeParser,
+} from '@stream-io/i18n';
+import { createTranslationContext } from '@stream-io/i18n/react';
+
+import type { StreamTFunction, TDateTimeParser } from './types';
+
+export type TranslationContextValue = {
+  t: StreamTFunction;
+  tDateTimeParser: TDateTimeParser;
+};
+
+/**
+ * The `t` in force before i18next has initialized, and the context's default.
+ *
+ * Core's factory, instantiated against this SDK's catalog so it is typed exactly like the real `t`.
+ * It honours the inline `defaultValue` each prose call site passes, which is what stops raw dotted
+ * keys flashing on the first frame.
+ */
+const defaultTranslatorFunction =
+  createDefaultTranslatorFunction() as StreamTFunction;
+
+/**
+ * Built from the shared factory in `@stream-io/i18n/react`.
+ *
+ * A **default value** is supplied rather than making the hook throw, and that is deliberate: it
+ * matches what `useI18n` did before this module existed, and it is what lets the `embedded/`
+ * components — which are used standalone, outside any provider — render correct English instead of
+ * crashing. Chat's React Native SDK throws instead; hence core exposes this as a factory.
+ */
+const { TranslationContext, TranslationProvider, useTranslationContext } =
+  createTranslationContext<TranslationContextValue>({
+    defaultValue: {
+      t: defaultTranslatorFunction,
+      tDateTimeParser: defaultDateTimeParser,
+    },
+    displayName: 'StreamVideoTranslationContext',
+  });
+
+export { TranslationContext, TranslationProvider };
+
+/**
+ * Reads `t` and `tDateTimeParser` from the closest provider.
+ *
+ * Works outside a provider too — the default translator renders each call site's inline English.
+ *
+ * The name is `useI18n` rather than core's `useTranslationContext` because ~500 call sites in this
+ * SDK already import it; renaming them is churn with no payoff.
+ *
+ * @example
+ * const { t } = useI18n();
+ * const label = t('callControls.cancelCallButton.leaveCall.title', 'Leave call');
+ */
+export const useI18n = useTranslationContext;

package/src/i18n/index.ts

@@ -0,0 +1,22 @@
+export * from './Streami18n';
+export * from './TranslationContext';
+export * from './types';
+export * from './useStreami18n';
+
+/**
+ * Core helpers re-exported so an integrator never needs a direct dependency on `@stream-io/i18n`:
+ * that package is an implementation detail of this SDK, and a second copy resolved from their
+ * `node_modules` would register dayjs plugins on the wrong module.
+ *
+ * - `asDynamicKey` — brands a runtime-resolved string as a translation key, the one sanctioned way
+ *   past the compile-time key check.
+ * - `getDateString` — the timestamp renderer, for a custom component formatting dates itself.
+ * - `predefinedFormatters` — the built-in i18next formatters, to spread over when adding one.
+ * - `defaultDateTimeParser` — the dayjs-backed parser, with the required plugins already applied.
+ */
+export {
+  asDynamicKey,
+  defaultDateTimeParser,
+  getDateString,
+  predefinedFormatters,
+} from '@stream-io/i18n';

package/src/i18n/keys.ts

@@ -0,0 +1,169 @@
+// AUTO-GENERATED — do not edit by hand.
+// Regenerate with `yarn build-translations`. CI fails if this file is out of sync.
+//
+// Type-only: no runtime value is emitted, so this adds nothing to the bundle.
+
+/**
+ * Every translation entry shipped with the SDK, mapped to its English copy.
+ *
+ * Plural entries appear as `<key>_one` / `<key>_other`; call sites use the bare `<key>` and
+ * pass `count`.
+ */
+export type TranslationCatalog = {
+  'callControls.blurToggleButton.applying.label': 'Applying...';
+  'callControls.blurToggleButton.blurBackground.label': 'Blur background';
+  'callControls.blurToggleButton.disableBlur.label': 'Disable blur';
+  'callControls.cancelCallButton.endCallForAll.label': 'End call for all';
+  'callControls.cancelCallButton.leaveCall.title': 'Leave call';
+  'callControls.reactionsButton.reactions.title': 'Reactions';
+  'callControls.recordCallButton.confirmEndRecording.description': 'Are you sure you want end the recording?';
+  'callControls.recordCallButton.endRecording.title': 'End recording';
+  'callControls.recordCallButton.recordCall.title': 'Record call';
+  'callControls.recordCallButton.waitingRecordingStart.title': 'Waiting for recording to start...';
+  'callControls.recordCallButton.waitingRecordingStop.title': 'Waiting for recording to stop...';
+  'callControls.screenShareButton.awaitingApproval.text': 'Awaiting for an approval to share screen.';
+  'callControls.screenShareButton.permissionGranted.text': 'You can now share your screen.';
+  'callControls.screenShareButton.permissionRevoked.text': 'You can no longer share your screen.';
+  'callControls.screenShareButton.shareScreen.title': 'Share screen';
+  'callControls.toggleAudioButton.awaitingApproval.text': 'Awaiting for an approval to speak.';
+  'callControls.toggleAudioButton.checkBrowserAudioPermissions.title': 'Check your browser audio permissions';
+  'callControls.toggleAudioButton.checkBrowserMicPermissions.title': 'Check your browser mic permissions';
+  'callControls.toggleAudioButton.mic.title': 'Mic';
+  'callControls.toggleAudioButton.microphonePausedBySystem.title': 'Microphone is paused by your system';
+  'callControls.toggleAudioButton.noPermissionToShareAudio.title': 'You have no permission to share your audio';
+  'callControls.toggleAudioButton.permissionGranted.text': 'You can now speak.';
+  'callControls.toggleAudioButton.permissionRevoked.text': 'You can no longer speak.';
+  'callControls.toggleAudioOutputButton.speakers.title': 'Speakers';
+  'callControls.toggleVideoButton.awaitingApproval.text': 'Awaiting for an approval to share your video.';
+  'callControls.toggleVideoButton.cameraPausedBySystem.title': 'Camera is paused by your system';
+  'callControls.toggleVideoButton.checkBrowserVideoPermissions.title': 'Check your browser video permissions';
+  'callControls.toggleVideoButton.noPermissionToShareVideo.title': 'You have no permission to share your video';
+  'callControls.toggleVideoButton.permissionGranted.text': 'You can now share your video.';
+  'callControls.toggleVideoButton.permissionRevoked.text': 'You can no longer share your video.';
+  'callControls.toggleVideoButton.video.title': 'Video';
+  'callControls.toggleVideoButton.videoPublishingDisabled.title': 'Video publishing is disabled by the system';
+  'callFeedback.callEndedScreen.callEnded.title': 'Call ended';
+  'callFeedback.callEndedScreen.helpUsImprove.text': 'Help us improve';
+  'callFeedback.callEndedScreen.leaveFeedback.label': 'Leave feedback';
+  'callFeedback.callEndedScreen.leftByMistake.text': 'Left by mistake?';
+  'callFeedback.callEndedScreen.rejoinCall.label': 'Rejoin call';
+  'callFeedback.ratingScreen.feedbackMessage.ariaLabel': 'Feedback message';
+  'callFeedback.ratingScreen.shareYourFeedback.title': 'Share your feedback';
+  'callFeedback.ratingScreen.submitFeedback.label': 'Submit feedback';
+  'callFeedback.ratingScreen.tellUsAboutExperience.placeholder': 'Tell us about your experience...';
+  'callFeedback.starRating.howWasCallQuality.text': 'How was your call quality?';
+  'callFeedback.starRating.rateStars.ariaLabel_one': 'Rate {{ count }} star';
+  'callFeedback.starRating.rateStars.ariaLabel_other': 'Rate {{ count }} stars';
+  'callFeedback.thankYouScreen.feedbackHelpsImprove.text': 'Your feedback helps improve call quality.';
+  'callFeedback.thankYouScreen.thankYou.title': 'Thank you!';
+  'callLayout.paginatedGridLayout.nextPage.ariaLabel': 'Next page';
+  'callLayout.paginatedGridLayout.previousPage.ariaLabel': 'Previous page';
+  'callLayout.speakerLayout.scrollParticipantsDown.ariaLabel': 'Scroll participants down';
+  'callLayout.speakerLayout.scrollParticipantsLeft.ariaLabel': 'Scroll participants left';
+  'callLayout.speakerLayout.scrollParticipantsRight.ariaLabel': 'Scroll participants right';
+  'callLayout.speakerLayout.scrollParticipantsUp.ariaLabel': 'Scroll participants up';
+  'callRecordingList.callRecordings.title': 'Call Recordings';
+  'callRecordingList.refresh.title': 'Refresh';
+  'common.allow.label': 'Allow';
+  'common.cancel.label': 'Cancel';
+  'common.default.label': 'Default';
+  'common.dismiss.label': 'Dismiss';
+  'common.live.label': 'Live';
+  'common.microphone.label': 'Microphone';
+  'common.noCameraFound.text': 'No camera found';
+  'common.participants.label': 'Participants';
+  'common.presentingYourScreen.text': 'You are presenting your screen';
+  'common.revoke.label': 'Revoke';
+  'common.speaker.label': 'Speaker';
+  'common.toggleMenu.ariaLabel': 'Toggle menu';
+  'common.tryAgain.label': 'Try again';
+  'common.videoDisabled.text': 'Video is disabled';
+  'common.waitingForPermission.title': 'Waiting for permission';
+  'connectionNotification.failedToRestore.text': 'Failed to restore connection. Please try again.';
+  'connectionNotification.joining.text': 'Joining';
+  'connectionNotification.migrating.text': 'Migrating...';
+  'connectionNotification.offline.text': 'You are offline. Check your internet connection.';
+  'connectionNotification.reconnecting.text': 'Reconnecting...';
+  'deviceSettings.selectCamera.title': 'Select a Camera';
+  'deviceSettings.selectMic.title': 'Select a Mic';
+  'deviceSettings.selectSpeakers.title': 'Select Speakers';
+  'deviceSettings.speakerTest.stopTest.label': 'Stop test';
+  'deviceSettings.speakerTest.testSpeaker.label': 'Test speaker';
+  'deviceSettings.toggleDeviceMenu.title': 'Toggle device menu';
+  'joinError.couldNotConnect.text': "We couldn't connect to the server. Please check your connection and try again.";
+  'joinError.failedToJoin.title': 'Failed to join the call';
+  'livestream.backstage.participantsJoinedEarly.text_one': '{{ formattedCount }} participant joined early';
+  'livestream.backstage.participantsJoinedEarly.text_other': '{{ formattedCount }} participants joined early';
+  'livestream.backstage.startsAt.text': 'Livestream starts at {{ time }}';
+  'livestream.backstage.startsSoon.text': 'Livestream starts soon';
+  'livestreamHost.backstage.text': 'Backstage';
+  'livestreamHost.endLive.label': 'End Live';
+  'livestreamHost.endStream.title': 'End Stream';
+  'livestreamHost.enterBackstage.label': 'Enter Backstage';
+  'livestreamHost.goLive.label': 'Go Live';
+  'livestreamHost.prepareLivestream.title': 'Prepare your livestream';
+  'livestreamHost.readyToGoLive.title': 'Ready to go live';
+  'livestreamHost.startStream.title': 'Start Stream';
+  'livestreamViewer.lobby.joinAutomatically.text': 'Join automatically when stream starts';
+  'livestreamViewer.lobby.joinStream.label': 'Join Stream';
+  'livestreamViewer.lobby.streamReady.title': 'Stream is ready!';
+  'livestreamViewer.lobby.waitingForStart.title': 'Waiting for the livestream to start';
+  'lobby.deviceControls.permissionNeeded.label': 'Permission needed';
+  'lobby.join.label': 'Join';
+  'lobby.setUpYourCall.title': 'Set up your call before joining';
+  'lobby.videoPreviewFallbacks.grantBrowserPermission.text': 'Please grant your browser permission to access your camera and microphone.';
+  'notification.micCaptureError.text': 'Your microphone is not capturing audio. Please check your setup.';
+  'notification.recordingInProgress.text': 'Recording in progress...';
+  'notification.speakingWhileMuted.text': 'You are muted. Unmute to speak.';
+  'participantList.anonymousCount.text': ', and ({{ anonymousCount }}) anonymous';
+  'participantList.cameraOff.title': 'Camera off';
+  'participantList.cameraOn.title': 'Camera on';
+  'participantList.me.text': 'Me';
+  'participantList.microphoneOff.title': 'Microphone off';
+  'participantList.microphoneOn.title': 'Microphone on';
+  'participantList.muteAll.label': 'Mute all';
+  'participantList.noParticipantsFound.text': 'No participants found';
+  'participantList.pinned.title': 'Pinned';
+  'participantList.unknown.text': 'Unknown';
+  'participantView.actionsMenu.allowAudio.label': 'Allow audio';
+  'participantView.actionsMenu.allowScreenSharing.label': 'Allow screen sharing';
+  'participantView.actionsMenu.allowVideo.label': 'Allow video';
+  'participantView.actionsMenu.block.label': 'Block';
+  'participantView.actionsMenu.disableAudio.label': 'Disable audio';
+  'participantView.actionsMenu.disableScreenSharing.label': 'Disable screen sharing';
+  'participantView.actionsMenu.disableVideo.label': 'Disable video';
+  'participantView.actionsMenu.enterFullscreen.label': 'Enter fullscreen';
+  'participantView.actionsMenu.enterPip.label': 'Enter picture-in-picture';
+  'participantView.actionsMenu.kick.label': 'Kick';
+  'participantView.actionsMenu.leaveFullscreen.label': 'Leave fullscreen';
+  'participantView.actionsMenu.leavePip.label': 'Leave picture-in-picture';
+  'participantView.actionsMenu.muteAudio.label': 'Mute audio';
+  'participantView.actionsMenu.muteScreenShareAudio.label': 'Mute screen share audio';
+  'participantView.actionsMenu.pin.label': 'Pin';
+  'participantView.actionsMenu.pinForEveryone.label': 'Pin for everyone';
+  'participantView.actionsMenu.turnOffScreenShare.label': 'Turn off screen share';
+  'participantView.actionsMenu.turnOffVideo.label': 'Turn off video';
+  'participantView.actionsMenu.unpinForEveryone.label': 'Unpin for everyone';
+  'participantView.audioBlocked.description': 'Click or tap to play audio';
+  'participantView.audioBlocked.title': 'Audio is blocked by your system';
+  'participantView.audioConnecting.title': 'Audio is connecting...';
+  'participantView.connectionQuality.poor.text': 'Poor connection quality. Please check your internet connection.';
+  'participantView.moreOptions.title': 'More options';
+  'participantView.stopScreenSharing.label': 'Stop Screen Sharing';
+  'participantView.unpin.label': 'Unpin';
+  'participantView.videoConnecting.title': 'Video is connecting...';
+  'participantView.videoPausedInsufficientBandwidth.title': 'Video paused due to insufficient bandwidth';
+  'permissions.requestingCamera.text': '{{ userName }} is requesting to share their camera';
+  'permissions.requestingPermission.text': '{{ userName }} is requesting permission: {{ permission }}';
+  'permissions.requestingScreenShare.text': '{{ userName }} is requesting to present their screen';
+  'permissions.requestingToSpeak.text': '{{ userName }} is requesting to speak';
+  'ringingCall.callingState.joined.text': 'Joined';
+  'ringingCall.callingState.joining.text': 'Joining';
+  'ringingCall.callingState.left.text': 'Left call';
+  'ringingCall.callingState.migrating.text': 'Migrating';
+  'ringingCall.callingState.offline.text': 'No internet connection';
+  'ringingCall.callingState.reconnecting.text': 'Re-connecting';
+  'ringingCall.callingState.reconnectingFailed.text': 'Failed';
+  'ringingCall.callingState.ringing.text': 'Ringing';
+  'videoPlaceholder.videoPlayingInPopup.text': 'Video is playing in a popup';
+};

package/src/i18n/runtimeDefaults.ts

@@ -0,0 +1,17 @@
+/**
+ * The SDK's bundled translation data: the keys that cannot carry an inline `defaultValue` at their
+ * call site. `Streami18n` layers it under *every* language, so a partial dictionary never knocks
+ * these out.
+ *
+ * Empty, and that is the intended steady state. The four lookups this SDK resolved from a runtime
+ * value — the only candidates for an entry here — are written as `switch` statements over literal
+ * `t()` calls instead, so every branch carries its own English copy inline and the codegen reads it
+ * straight off the call site. Nothing is left without a default. `timestamp.*` / `duration.*`
+ * formatter expressions would also live here; this SDK has none yet.
+ *
+ * Adding an entry later needs no wiring. `Streami18n` already spreads this into the core options and
+ * `scripts/generate-i18n-keys.mts` already reads this path, so a new key reaches `keys.ts` on the
+ * next `build-translations` run — where a key nothing references, or one that shadows an inline
+ * default, fails a codegen guard.
+ */
+export const runtimeDefaults = {};

package/src/i18n/types.ts

@@ -0,0 +1,78 @@
+import type {
+  Streami18nState as CoreStreami18nState,
+  LooseTranslationDictionaryOf,
+  RelativeTimeCatalog,
+  StreamTFunctionFor,
+  TranslationDictionaryOf,
+  TranslationKeyOf,
+} from '@stream-io/i18n';
+
+import type { TranslationCatalog as GeneratedCatalog } from './keys';
+
+/**
+ * The SDK's i18n types, instantiated from the generic helpers in `@stream-io/i18n`.
+ *
+ * The derivations live in core so both video SDKs (and Chat) share one implementation; the *catalog*
+ * stays here, because it is generated from this package's own `t()` call sites. That split is why
+ * core's helpers are generic over the catalog rather than driven by module augmentation — two
+ * catalogs have to be able to coexist in one TypeScript program, which a monorepo typechecking the
+ * web and React Native SDKs in one pass does.
+ *
+ * `relativeTime.*` is intersected in because it is core's copy, not ours: `timestampFormatter`
+ * renders "Today" / "3d ago" through `t()`, and without these keys in the catalog an integrator
+ * could not type a dictionary that translates them.
+ */
+export type TranslationCatalog = GeneratedCatalog & RelativeTimeCatalog;
+
+/**
+ * Keys resolved from bundled data rather than from an inline `defaultValue`.
+ *
+ * `never`, because `runtimeDefaults.ts` is empty — every key this SDK uses is written literally
+ * with its English copy at the call site. `timestamp.*` / `duration.*` are matched by prefix inside
+ * core and need no entry here.
+ *
+ * **It must never become `string`.** `string` collapses the prose overload in `StreamTFunctionFor`,
+ * which silently disables all key checking: every `t('typo.key', 'copy')` would compile. Widen it
+ * only to a literal prefix template (`` `foo.${string}` ``) when a real bundled key appears.
+ */
+export type BundledKey = never;
+
+export type TranslationKey = TranslationKeyOf<TranslationCatalog>;
+export type TranslationDictionary = TranslationDictionaryOf<TranslationCatalog>;
+export type LooseTranslationDictionary =
+  LooseTranslationDictionaryOf<TranslationCatalog>;
+export type StreamTFunction = StreamTFunctionFor<
+  TranslationCatalog,
+  BundledKey
+>;
+
+/**
+ * The value held by `Streami18n.state`, parameterized for this SDK's catalog.
+ *
+ * Exported because `state` is public: a consumer subscribing to it needs to name the type for a
+ * module-scope selector. Core's default-parameterized `Streami18nState` is not a substitute — `t` is
+ * contravariant in its key parameter, so that one is not assignable to this.
+ */
+export type Streami18nState = CoreStreami18nState<
+  TranslationCatalog,
+  BundledKey
+>;
+
+/**
+ * Re-exported so an integrator can type a formatter, a locale config or a date parser without
+ * taking a direct dependency on `@stream-io/i18n`.
+ */
+export type {
+  CustomFormatters,
+  DateTimeParserModule,
+  DayjsLocaleConfig,
+  DurationFormatterOptions,
+  DynamicTranslationKey,
+  FormatterFactory,
+  LooseTranslateFunction,
+  PredefinedFormatters,
+  TDateTimeParser,
+  TDateTimeParserInput,
+  TDateTimeParserOutput,
+  TimestampFormatterOptions,
+} from '@stream-io/i18n';

package/src/i18n/useStreami18n.ts

@@ -0,0 +1,66 @@
+import { useEffect, useState } from 'react';
+import { useStreami18nState } from '@stream-io/i18n/react';
+
+import { Streami18n } from './Streami18n';
+import type { TranslationContextValue } from './TranslationContext';
+import type { LooseTranslationDictionary } from './types';
+
+export type UseStreami18nParams = {
+  /** An instance the integrator configured. One is created when absent. */
+  i18nInstance?: Streami18n;
+  /** The language the SDK's copy renders in. Changing it switches languages in place. */
+  language?: string;
+  /** Dictionaries to register, keyed by language code. Partial dictionaries are safe. */
+  translations?: Record<string, LooseTranslationDictionary>;
+};
+
+/**
+ * Resolves the translation context value: creates or adopts a {@link Streami18n} instance,
+ * registers the supplied dictionaries, initializes it and keeps `t` fresh across language changes.
+ *
+ * `init()` and the store subscription belong to `useStreami18nState` in `@stream-io/i18n/react`,
+ * shared with the React Native SDK.
+ */
+export const useStreami18n = ({
+  i18nInstance,
+  language,
+  translations,
+}: UseStreami18nParams): TranslationContextValue => {
+  // Lazy `useState`, not `useMemo`: `new Streami18n()` is a real allocation with identity that must
+  // survive a re-render, and this repo lints `react-hooks/purity` as an error — `useMemo` is a
+  // cache React is free to drop, so constructing there is a purity violation. A later change to
+  // `i18nInstance` is ignored on purpose; swapping the instance mid-tree is not a supported move.
+  const [i18n] = useState(() => {
+    const instance = i18nInstance ?? new Streami18n({ language });
+
+    // Registered here rather than in an effect. `useStreami18nState` calls `init()` from its own
+    // effect, which runs *before* any effect declared below it in this hook — so a dictionary
+    // registered in an effect would arrive after i18next was already initialized, and the first
+    // `init()` would warn that the language has no dictionary.
+    if (translations) {
+      for (const [code, dictionary] of Object.entries(translations)) {
+        instance.registerTranslation(code, dictionary);
+      }
+    }
+
+    return instance;
+  });
+
+  // No `onInitError` handler: core already logs a warning and leaves the instance usable, with `t`
+  // still rendering each call site's inline English. Pass one only to surface init failures
+  // somewhere other than the console.
+  const translators = useStreami18nState(i18n);
+
+  useEffect(() => {
+    // Guarded on the current value: `setLanguage` re-runs the formatter factories and a full
+    // i18next `changeLanguage`, and the first render already constructed the instance with
+    // `language`. Undefined means "leave whatever the instance was configured with".
+    if (!language || i18n.currentLanguage === language) return;
+    i18n.setLanguage(language);
+  }, [i18n, language]);
+
+  // Returned as-is: `useStreami18nState` already caches this object and only produces a new one
+  // when `t` or `tDateTimeParser` actually changes, so wrapping it in a `useMemo` would add a
+  // second cache over a stable value.
+  return translators;
+};