README.md

@mango.dev/react

React bindings for @mango.dev/core — provides a context provider and hook to read and switch languages in your React app.

Features

• MangoProvider — wraps your app and supplies language context to all child components
• useMango hook — access the current language, switch languages, and resolve multilingual fields
• t() helper — resolves any translated field (or plain primitive) to a displayable string for the active language
• Type-safe language switching — setLang only accepts languages defined in the provider
• Fallback support — if a translation is missing for the active language, falls back to the first language in the list
• React 18+ compatible, built for client components

Installation

# npm
npm install @mango.dev/react @mango.dev/core

# pnpm
pnpm add @mango.dev/react @mango.dev/core

# yarn
yarn add @mango.dev/react @mango.dev/core

Peer dependencies: react >= 18, react-dom >= 18

Usage

1. Wrap your app with MangoProvider

The langs array must match exactly what you passed to new Mango({ langs }) in your backend/server code.

import { MangoProvider } from "@mango.dev/react";

const LANGS = ["en", "es", "fr"] as const;

export default function App() {
  return (
    <MangoProvider langs={LANGS} defaultLang="en">
      <YourApp />
    </MangoProvider>
  );
}

2. Render translated fields with useMango() — t()

Type your component props with Translated<T> from @mango.dev/core to get full autocomplete on t() calls.

import { useMango } from "@mango.dev/react";
import type { Translated } from "@mango.dev/core";

type Post = { title: string; body: string; slug: string };
type TranslatedPost = Translated<Post, "slug", "en" | "es" | "fr">;
// → { title: Record<"en"|"es"|"fr", string>; body: Record<...>; slug: string }

export function PostCard({ post }: { post: TranslatedPost }) {
  const { t } = useMango();

  return (
    <div>
      <h1>{t(post.title)}</h1>
      <p>{t(post.body)}</p>
      <p>{t(post.slug)}</p>
    </div>
  );
}

3. Switch languages with useMango() — setLang

import { useMango } from "@mango.dev/react";

export function LanguageSwitcher() {
  const { lang, setLang, langs } = useMango();

  return (
    <div>
      {langs.map((l) => (
        <button key={l} onClick={() => setLang(l)} disabled={l === lang}>
          {l}
        </button>
      ))}
    </div>
  );
}

4. How t() works

t() resolves any field — translated or plain — to a displayable value for the active language.

// Translated field (from @mango.dev/core output)
t(post.title)  // { en: "Hello", es: "Hola", fr: "Bonjour" } → "Hello" (if lang is "en")

// Primitive field — returned as-is
t(post.id)     // 42          → 42
t(post.slug)   // "my-post"   → "my-post"

If the active language has no translation, t() falls back to the first language in the langs list.

Configuration

MangoProviderProps

Prop	Type	Required	Description
langs	string[]	✅	All supported languages — must match @mango.dev/core config
defaultLang	string	✅	Active language on first render
children	React.ReactNode	✅	Child components

useMango return value

Property	Type	Description
lang	string	Currently active language
setLang	(lang: string) => void	Switch the active language
t	(field) => string | number | boolean	Resolve a multilingual field to the active language
langs	string[]	All available languages

useMango() must be called inside a <MangoProvider> — it throws a descriptive error otherwise.