@sonardigital/translations

A tiny React/i18next helper that bootstraps i18n, provides a lightweight context, and exposes ergonomic hooks for app-wide translations and namespaced keys.

Installation

npm install @sonardigital/translations i18next react-i18next
# or
yarn add @sonardigital/translations i18next react-i18next

What this gives you

• Provider: TranslationsWrapper to wire translations and language into context
• Hooks:
  • useTranslations to initialize i18n and expose { t, i18n, changeLanguage, language }
  • useTranslationsContext to read the shared context anywhere
  • useNamespaceT(namespace) to prefix keys like COMMONS.title
• Utilities:
  • initializeI18n(resources, lng) and createI18nInstance(language, resources)
  • getDeviceLanguage()
• Constants: DEFAULT_LANGUAGE, LANGUAGE_OPTIONS, LANGUAGE_STORAGE_KEY

Minimal example

import React from 'react';
import { createRoot } from 'react-dom/client';
import {
  TranslationsWrapper,
  useTranslationsContext,
  useNamespaceT,
  DEFAULT_LANGUAGE,
} from '@sonardigital/translations';

const resources = {
  en: { translation: { hello: 'Hello', COMMONS: { title: 'Home' } } },
  it: { translation: { hello: 'Ciao', COMMONS: { title: 'Home' } } },
};

function App() {
  const { t, changeLanguage, language } = useTranslationsContext();
  const tc = useNamespaceT('COMMONS');

  return (
    <div>
      <h1>{tc('title')}</h1>
      <p>{t('hello')}</p>
      <button onClick={() => changeLanguage(language === 'en' ? 'it' : 'en')}>
        Switch language
      </button>
    </div>
  );
}

createRoot(document.getElementById('root')!).render(
  <TranslationsWrapper language={DEFAULT_LANGUAGE} translations={resources}>
    <App />
  </TranslationsWrapper>
);

API

• TranslationsWrapper props:

  • language?: string – initial language. If omitted, uses current i18next language
  • translations: Record<string, unknown> – i18next resources object { [lng]: { translation: { ... } } }
  • methods?: return of useTranslations to override provided methods

• useTranslations({ language?, translations }) → { t, i18n, changeLanguage, language }

  • Initializes i18n once with initializeI18n and keeps language in sync

• useTranslationsContext() → same shape as above, from context

• useNamespaceT(namespace: string) → (key: string, options?) => string

  • Returns a t that prefixes keys with ${namespace}.

• initializeI18n(resources, lng)

  • Sets up i18next with react-i18next; default ns is translation, useSuspense: false

• createI18nInstance(language, resources)

  • Creates and returns a detached i18n instance (advanced/SSR)

• getDeviceLanguage()

  • Returns browser language or DEFAULT_LANGUAGE

• Constants: DEFAULT_LANGUAGE = 'it', LANGUAGE_OPTIONS, LANGUAGE_STORAGE_KEY

Resource shape

const resources = {
  en: {
    translation: {
      hello: 'Hello',
      COMMONS: { title: 'Home' },
    },
  },
  it: {
    translation: {
      hello: 'Ciao',
      COMMONS: { title: 'Home' },
    },
  },
};

Notes

• The library disables escaping in interpolation (escapeValue: false) and disables React suspense in config.
• If you already have i18next initialized, you can pass methods to TranslationsWrapper to reuse your instance and configuration.

License

ISC