@comvi/solid API Reference

@comvi/solid provides SolidJS signals-based reactivity, an <I18nProvider> for context-based access, and a <T> component for safe rich-text interpolation. It builds on top of @comvi/core and re-exports all core APIs.

<I18nProvider>

Wraps your component tree and provides the i18n instance via SolidJS context. Required for useI18n() and useI18nContext().

import { I18nProvider } from '@comvi/solid';
import { i18n } from './i18n';

function App() {
  return (
    <I18nProvider i18n={i18n}>
      <MyApp />
    </I18nProvider>
  );
}

Props

Prop	Type	Default	Description
i18n	I18n	—	The i18n instance created by createI18n() (required)
autoInit	boolean	true	Whether to auto-initialize the i18n instance on mount
children	JSX.Element	—	Child components that need access to translations

Note

When autoInit is true (default), the provider calls i18n.init() automatically on mount. Set to false if you initialize the i18n instance manually before rendering.

useI18n(ns?)

The primary hook for translating strings and reading i18n state. Returns an object with reactive accessors and i18n methods.

import { useI18n } from '@comvi/solid';

function MyComponent() {
  const { t, locale, setLocale, isLoading } = useI18n();

  return (
    <Show when={!isLoading()} fallback={<div>Loading...</div>}>
      <h1>{t('hello.world')}</h1>
      <p>{t('greeting', { name: 'Alice' })}</p>
      <p>Current locale: {locale()}</p>
    </Show>
  );
}

Signature

useI18n(ns?: string): UseI18nReturn

Pass an optional namespace string to scope all t() calls to that namespace.

Returned Values

interface UseI18nReturn {
  t(key, params?): string;
  tRaw(key, params?): TranslationResult;
  locale: Accessor<string>;             // call as function: locale()
  isLoading: Accessor<boolean>;
  isInitializing: Accessor<boolean>;
  isInitialized: Accessor<boolean>;
  cacheRevision: Accessor<number>;
  setLocale, addTranslations, addActiveNamespace, setFallbackLocale,
  onMissingKey, onLoadError, clearTranslations, reloadTranslations,
  hasLocale, hasTranslation, getLoadedLocales, getActiveNamespaces,
  getDefaultNamespace, getTranslationCache, on, reportError,
  formatNumber, formatDate, formatCurrency, formatRelativeTime,
  dir: () => "ltr" | "rtl"
}

In JSX, accessing t('key') automatically tracks locale and cacheRevision.

useI18n('admin') binds default namespace; t('key') resolves to admin:key.

Namespace Scoping

function Dashboard() {
  const { t } = useI18n('dashboard');

  // Keys are scoped — no need for { ns: 'dashboard' }
  return <h1>{t('page.title')}</h1>;
}

useI18nContext()

Returns the raw i18n instance from the nearest <I18nProvider>. Use this when you need direct access to the instance for imperative operations.

import { useI18nContext } from '@comvi/solid';

function AdvancedComponent() {
  const i18n = useI18nContext();

  createEffect(() => {
    const unsub = i18n.on('localeChanged', ({ to }) => {
      console.log('Language changed to:', to);
    });
    onCleanup(unsub);
  });

  return <div>...</div>;
}

<T> Component

The <T> component renders translations containing rich content (HTML tags, SolidJS components) safely.

import { T } from '@comvi/solid';

Props

The <T> component accepts these props:

Prop	Type	Notes
i18nKey	string	required
params	TranslationParams	interpolation params
ns	string	namespace
locale	string	override locale
fallback	string	fallback text
raw	boolean	forwards raw: true to post-processors that support it, such as the in-context editor marker injector
components	ComponentMap	tag map (string, function, or { tag, props })
children	JSX.Element	fallback content

Basic Usage

{/* Translation: "Hello, {name}!" */}
<T i18nKey="greeting" params={{ name: 'Alice' }} />

Rich Text with Components

{/* Translation: "Read our <link>terms of service</link>" */}
<T
  i18nKey="legal.tos"
  components={{
    link: { tag: 'a', props: { href: '/terms' } },
  }}
/>

Component Map Types

The components prop accepts three kinds of mappings:

<T
  i18nKey="rich.message"
  components={{
    // 1. HTML tag name
    bold: 'strong',

    // 2. SolidJS component function
    highlight: ({ children }) => <mark class="bg-yellow-200">{children}</mark>,

    // 3. Tag with props
    link: { tag: 'a', props: { href: '/about', class: 'text-blue-600' } },
  }}
/>

Fallback Content

{/* Renders children if translation key is not found */}
<T i18nKey="optional.feature">
  <p>Default content</p>
</T>

Reactive Primitives

For advanced use cases, @comvi/solid exports low-level signal creators that bridge the i18n event system to SolidJS signals. These must be called within a reactive context (component or effect).

Primitive	Returns	Tracks
createLocaleSignal(i18n)	Accessor<string>	localeChanged events
createDefaultNamespaceSignal(i18n)	Accessor<string>	defaultNamespaceChanged events
createLoadingSignal(i18n)	Accessor<boolean>	loadingStateChanged events
createInitializingSignal(i18n)	Accessor<boolean>	loadingStateChanged events
createInitializedSignal(i18n)	Accessor<boolean>	initialized / destroyed events
createCacheRevisionSignal(i18n)	Accessor<number>	namespaceLoaded / translationsCleared events

import { createLocaleSignal, createLoadingSignal } from '@comvi/solid';

// Inside a component or reactive context
const locale = createLocaleSignal(i18n);
const isLoading = createLoadingSignal(i18n);

Tip

You rarely need these directly. The <I18nProvider> creates and manages all signals automatically, and useI18n() exposes them as reactive accessors.

Core Exports

@comvi/solid re-exports createI18n, I18n, and all types from @comvi/core. Import other core value exports from @comvi/core directly.

See the @comvi/core API Reference for the full list.

Next Steps

SolidJS Integration Guide Step-by-step setup and patterns for SolidJS apps.

Translation Function Deep dive into the t() function, parameters, and pluralization.

Type-Safe Translations Enable autocomplete and compile-time checks for translation keys.

@comvi/core API Framework-agnostic core API reference.