Quick Start (React)

1. Install packages

   pnpm add @fluenti/core @fluenti/react
   pnpm add -D @fluenti/cli @fluenti/vite-plugin

2. Configure Vite

   vite.config.ts

   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   import fluenti from '@fluenti/vite-plugin'
   
   export default defineConfig({
     plugins: [
       fluenti({ framework: 'react' }),
       react(),
     ],
   })

3. Create fluenti.config.ts

   fluenti.config.ts

   import { defineConfig } from '@fluenti/cli'
   
   export default defineConfig({
     sourceLocale: 'en',
     locales: ['en', 'zh-CN'],
     catalogDir: './locales',
     format: 'po',
     include: ['./src/**/*.{tsx,ts,jsx}'],
     compileOutDir: './src/locales/compiled',
   })

4. Write your component — just use t “ and <Trans>

   src/Home.tsx

   import { useI18n } from '@fluenti/react'
   import { Trans, Plural } from '@fluenti/react'
   
   export function Home() {
     const { setLocale } = useI18n()
     const name = 'World'
     const count = 3
   
     return (
       <div>
         {/* t`` tagged template — compiler macro, no import needed */}
         <h1>{t`Welcome to my app`}</h1>
         <p>{t`Hello, ${name}!`}</p>
   
         {/* Rich text with real HTML — no XSS, no indexed placeholders */}
         <Trans>Read the <a href="/docs">documentation</a> to learn more.</Trans>
   
         {/* Locale-aware plurals */}
         <Plural value={count} one="# item in cart" other="# items in cart" />
   
         <button onClick={() => setLocale('en')}>English</button>
         <button onClick={() => setLocale('zh-CN')}>中文</button>
       </div>
     )
   }

   No manual keys. No JSON files. The t`...` tagged template is a compiler macro — the Vite plugin injects it automatically.

5. Extract messages

   npx fluenti extract

   This scans your source files and generates catalog files in ./locales/.

6. Add translations

   Open locales/zh-CN.po and fill in msgstr fields:

   msgid "Welcome to my app"
   msgstr "欢迎使用我的应用"
   
   msgid "Hello, {name}!"
   msgstr "你好，{name}！"

7. Compile messages

   npx fluenti compile

8. Initialize from compiled output

   src/main.tsx

   import { createRoot } from 'react-dom/client'
   import { I18nProvider } from '@fluenti/react'
   import { Home } from './Home'
   import en from './locales/compiled/en'
   import zhCN from './locales/compiled/zh-CN'
   
   function App() {
     return (
       <I18nProvider
         locale="en"
         fallbackLocale="en"
         messages={{ en, 'zh-CN': zhCN }}
       >
         <Home />
       </I18nProvider>
     )
   }
   
   createRoot(document.getElementById('root')!).render(<App />)

Rich text with <Trans>

import { Trans } from '@fluenti/react'

<Trans>Click <a href="/next">here</a> to continue.</Trans>
<Trans>This is <strong>important</strong> information.</Trans>

Plurals with <Plural>

import { Plural } from '@fluenti/react'

<Plural value={count} zero="No items" one="# item" other="# items" />

Framework compatibility

@fluenti/react works with any React-based framework:

• React SPA (Vite) — full Vite plugin support
• React Router — Quick Start (React Router)
• Next.js — Quick Start (Next.js)
• TanStack Start — Quick Start (TanStack Start)

Next steps

• React SPA guide — deeper patterns for React SPAs
• Translating Content — all translation APIs
• Configuration — full fluenti.config.ts reference