@magic-translate/react

React client for Magic Translate, AI-powered i18n without translation keys or language files. Write your components in one language, wrap the text in <T>, and Magic Translate translates it on the fly.

<button>
  <T>Create chord chart</T>
</button>

No t('editor.toolbar.create'), no en.json / de.json to keep in sync, and adding a language is one line. Translations are cached and can be edited by hand in the dashboard.

Requires React 17 or newer. For server-side rendering with Next.js or React Server Components, use @magic-translate/react-ssr.

Full docs: magictranslate.io/docs/react

Install

npm install --save @magic-translate/react

Or with yarn:

yarn add @magic-translate/react

Setup

Wrap your app in MagicTranslateProvider. You can get an API key for free at magictranslate.io.

// main.tsx
import { createRoot } from 'react-dom/client';
import { MagicTranslateProvider } from '@magic-translate/react';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <MagicTranslateProvider apiKey="YOUR_API_KEY" language="de">
    <App />
  </MagicTranslateProvider>
);

Usage

<T> component

Wrap any text, including plain HTML, in <T>. The original content is shown until its translation has loaded.

import { T } from '@magic-translate/react';

export const Welcome = ({ name }: { name: string }) => (
  <>
    <h1>
      <T>Welcome to our shop</T>
    </h1>
    <p>
      <T>
        Click <a href="/sale">here</a> to see <b>today's</b> deals.
      </T>
    </p>
    <p>
      <T>Hello {name}</T>
    </p>
  </>
);

The content is re-translated whenever it changes, for example when name changes in the example above.

All translations requested at the same time are sent to the API in a single request, and translations are cached, so you can use as many <T> components as you like.

Only text and plain HTML elements are allowed inside <T>. React components are not, because they cannot survive the translation; <T> throws if it finds one. Translate inside the component instead, or pass the translated string down as a prop.

useTranslate

Use useTranslate (or its alias useT) for plain strings, such as attributes, or anywhere a component does not fit:

import { useTranslate } from '@magic-translate/react';

export const Search = () => {
  const t = useTranslate();

  return <input placeholder={t('Search products')} />;
};

t returns the original text until the translation has loaded, and the component re-renders once it has.

Variables

Wrap values that change, such as names or counts, in v(). The text around them is translated once as a template, You have {0} unread messages, and cached, however many different values it is shown with. The values themselves are never sent to the API.

import { T, v } from '@magic-translate/react';

<T>
  Hello {v(user.name)}, you have {v(count)} unread messages
</T>;

The placeholders are numbered in order, and a translation can move them to wherever the language needs them. v() can also hold a React component, such as a link.

With t, use a tagged template. Every ${} value is treated the same way:

const t = useTranslate();

t`You have ${count} unread messages`;

Without v(), a value is translated as part of the text, so every different value is a new translation.

Options per translation

Both the component and t can override the target language and the formality:

<T lang="fr" formality="formal">How are you?</T>

<input placeholder={t('Your name', { lang: 'fr', formality: 'formal' })} />

Switching languages

useLanguageSwitcher reads and changes the current language. Every <T> component and t call updates automatically.

import { useLanguageSwitcher } from '@magic-translate/react';

export const LanguageSwitcher = () => {
  const { currentLanguage, setLanguage } = useLanguageSwitcher();

  return (
    <select
      value={currentLanguage}
      onChange={(e) => setLanguage(e.target.value as typeof currentLanguage)}
    >
      <option value="en">English</option>
      <option value="de">Deutsch</option>
      <option value="fr">Français</option>
    </select>
  );
};

Configuration

MagicTranslateProvider accepts:

Other frameworks

• @magic-translate/react-ssr: Next.js App Router and React Server Components
• @magic-translate/vue: Vue 3 and Nuxt
• @magic-translate/angular: Angular
• @magic-translate/js: any website, with one script tag

License

MIT © i42 GmbH