Skip to main content

React Integration

Translate your locale files at build time, then read them with react-i18next as usual.

View on GitHub

Features

No API key in the browser — translation happens before deploy
Works with react-i18next and any JSON-based runtime
Placeholders and <Trans> markup survive translation
Zero runtime dependency on Shipi18n

Prerequisites

  • 1.A React app with react-i18next
  • 2.An LLM API key used at build time only

Installation

npm install -D @shipi18n/cli
npm install react-i18next i18next

Configuration

Add a script that translates your source locale before the build. The key lives in your shell or CI secrets — it is never bundled, because this step runs before the bundler does.

{
  "scripts": {
    "i18n": "shipi18n translate src/locales/en.json -t es,fr,de --incremental",
    "build": "npm run i18n && vite build"
  }
}

Usage

const { t } = useTranslation(); return <p>{t('greeting', { name })}</p>

Examples

Consume the generated files

import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import en from './locales/en.json'
import es from './locales/es.json'
import fr from './locales/fr.json'

i18n.use(initReactI18next).init({
  resources: { en: { translation: en }, es: { translation: es }, fr: { translation: fr } },
  lng: 'en',
  fallbackLng: 'en',
  interpolation: { escapeValue: false },
})

Interpolation survives translation

// en.json  { "greeting": "Hello, {{name}}!" }
// es.json  { "greeting": "¡Hola, {{name}}!" }

function Welcome({ name }) {
  const { t } = useTranslation()
  return <p>{t('greeting', { name })}</p>
}

Best Practices

  • Translate before bundling, never at runtime — a browser must never hold an LLM key.
  • Commit the generated locale files so a deploy never depends on a model call.
  • Use --incremental so untouched strings stay byte-identical between builds.

Troubleshooting

Translations are missing at runtime

Check that the npm run i18n step ran before the build and that the generated files are imported in your i18n init.

A key renders as its own name

i18next falls back to the key when it is missing. Re-run the translate step; the key was probably added after the last run.

Need help? Read the docs

View on GitHub