@mounaji_npm/i18n

Internationalization (i18n) provider, hook, and language switcher for @mounaji_npm SaaS applications. Zero dependencies beyond React. Works standalone or integrated into AppShell.

Built-in languages: English (en), Spanish (es), Portuguese (pt), Chinese Simplified (zh), German (de).

Install

npm install @mounaji_npm/i18n

Quick Start

import { I18nProvider, useI18n, LanguageSwitcher } from '@mounaji_npm/i18n';

function Header() {
  const { t } = useI18n();
  return (
    <header>
      <span>{t('nav.dashboard')}</span>
      <LanguageSwitcher variant="compact" />
    </header>
  );
}

export default function App() {
  return (
    <I18nProvider defaultLocale="en" locales={['en', 'es', 'pt']}>
      <Header />
      <YourApp />
    </I18nProvider>
  );
}

I18nProvider

Wraps your app (or sub-tree). Handles locale state, localStorage persistence, and browser-language auto-detection.

import { I18nProvider } from '@mounaji_npm/i18n';

<I18nProvider
  defaultLocale="en"
  locales={['en', 'es', 'pt', 'zh', 'de']}
  persist={true}
  storageKey="mn_locale"
  detectBrowser={true}
>
  {children}
</I18nProvider>

| Prop | Type | Default | Description | |---|---|---|---| | defaultLocale | string | 'en' | Locale used on first load (overridden by localStorage or browser detection) | | locales | string[] | all built-ins | Restrict available locales | | translations | object | — | Custom translation overrides (merged with built-ins) | | persist | boolean | true | Save selected locale to localStorage | | storageKey | string | 'mn_locale' | localStorage key | | detectBrowser | boolean | true | Auto-detect browser language on first visit |

useI18n

Access translations and locale state from any component inside I18nProvider.

import { useI18n } from '@mounaji_npm/i18n';

function MyComponent() {
  const {
    t,                // (key: string, vars?: object) => string
    locale,           // current locale code: 'en' | 'es' | ...
    setLocale,        // (code: string) => void
    availableLocales, // string[] — locales prop of I18nProvider
    localeLabel,      // (code: string) => string — e.g. 'English', 'Español'
    localeFlag,       // (code: string) => string — e.g. '🇺🇸', '🇪🇸'
  } = useI18n();

  return (
    <div>
      <h1>{t('nav.dashboard')}</h1>
      <p>{t('common.welcome')}</p>
      <button onClick={() => setLocale('es')}>
        {localeFlag('es')} {localeLabel('es')}
      </button>
    </div>
  );
}

t() — Translation function

Uses dot-notation keys with {placeholder} interpolation.

const { t } = useI18n();

t('nav.dashboard')               // → "Dashboard"
t('nav.chat')                    // → "Chat"
t('common.save')                 // → "Save"
t('common.cancel')               // → "Cancel"
t('auth.signIn')                 // → "Sign in"
t('chat.messagesCount', { n: 5 })// → "5 messages"
t('unknown.key')                 // → "unknown.key" (key returned as fallback)

If the current locale is missing a key, t() automatically falls back to the English (en) value.

LanguageSwitcher

Token-driven dropdown for switching locales.

import { LanguageSwitcher } from '@mounaji_npm/i18n';

// Compact: flag + code (e.g. "🇺🇸 EN")
<LanguageSwitcher variant="compact" />

// Full: flag + full name (e.g. "🇺🇸 English")
<LanguageSwitcher variant="full" />

// Flags only
<LanguageSwitcher variant="flags-only" />

// Hide when only one locale is available
<LanguageSwitcher show={availableLocales.length > 1} />

| Prop | Type | Default | Description | |---|---|---|---| | variant | string | 'compact' | compact full flags-only | | show | boolean | true | Hide the switcher entirely when false | | className | string | — | Additional CSS class |

Built-in Translation Keys

All built-in locales cover these namespaces:

nav.*          — Sidebar/nav labels (dashboard, chat, assistants, …)
common.*       — Shared UI (save, cancel, delete, confirm, loading, …)
auth.*         — Login/logout (signIn, signOut, email, password, …)
shell.*        — AppShell UI (themeToggle, newProject, profile, …)
chat.*         — Chat UI (placeholder, send, emptyState, …)

Adding a Custom Language

Step 1 — Create the translation file:

// locales/fr.js
export default {
  nav: {
    dashboard:    'Tableau de bord',
    chat:         'Discussion',
    assistants:   'Assistants',
    knowledgeBase:'Base de connaissances',
    settings:     'Paramètres',
  },
  common: {
    save:    'Enregistrer',
    cancel:  'Annuler',
    delete:  'Supprimer',
    loading: 'Chargement…',
  },
  auth: {
    signIn:  'Se connecter',
    signOut: 'Se déconnecter',
  },
};

Step 2 — Pass via translations prop:

import fr from './locales/fr.js';

<I18nProvider
  defaultLocale="fr"
  locales={['en', 'es', 'fr']}
  translations={{ fr }}
>
  {children}
</I18nProvider>

Or extend the built-in locale registry (for library authors):

// In your app's locale registry
import { en, es, LOCALE_LABELS, LOCALE_FLAGS } from '@mounaji_npm/i18n';
import fr from './locales/fr.js';

export const locales = { en, es, fr };
export const labels  = { ...LOCALE_LABELS, fr: 'Français' };
export const flags   = { ...LOCALE_FLAGS,  fr: '🇫🇷' };

Integration with AppShell

@mounaji_npm/saas-template's AppShell accepts an i18n prop that activates the provider and injects LanguageSwitcher into the top nav automatically:

import { AppShell } from '@mounaji_npm/saas-template';

<AppShell
  modules={CORE_MODULES}
  activePath={pathname}
  i18n={{
    enabled:       true,
    defaultLocale: 'en',
    locales:       ['en', 'es', 'pt'],
    show:          true,           // show LanguageSwitcher in TopNav
  }}
>
  {children}
</AppShell>

Next.js Example

// app/providers.jsx
'use client';
import { I18nProvider } from '@mounaji_npm/i18n';

export function Providers({ children }) {
  return (
    <I18nProvider defaultLocale="en" locales={['en', 'es', 'pt']}>
      {children}
    </I18nProvider>
  );
}

// app/layout.js
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}