Tutorial

This tutorial walks you through building a React app with full i18n support using Fluenti and Vite. By the end, you will have a working app with English and Japanese translations.

What you will build

A small task manager app with:

• A greeting message with the user’s name
• A task counter with plural forms
• A locale switcher

1. Create a new project

   npm create vite@latest my-i18n-app -- --template react-ts
   cd my-i18n-app

2. Install Fluenti

   npm install @fluenti/core @fluenti/react
   npm install -D @fluenti/cli

3. Initialize Fluenti

   npx fluenti init

   When prompted, set source locale to en, target locales to ja, and format to po. This generates fluenti.config.ts and adds scripts to package.json.

4. Configure Vite

   Update vite.config.ts:

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

5. Write your component

   Replace src/App.tsx with a simple component that uses tagged templates for translation:

   import { I18nProvider, useI18n, t } from '@fluenti/react'
   
   function TaskApp() {
     const { setLocale, locale } = useI18n()
     return (
       <div>
         <h1>{t`Hello, ${'Alice'}!`}</h1>
         <p>{t`You have ${3} tasks today`}</p>
         <button onClick={() => setLocale(locale === 'en' ? 'ja' : 'en')}>
           {t`Switch language`}
         </button>
       </div>
     )
   }
   
   export default function App() {
     return (
       <I18nProvider locale="en" messages={{}}>
         <TaskApp />
       </I18nProvider>
     )
   }

6. Extract and translate

   Run npm run i18n:extract to generate PO catalogs, then open locales/ja.po and add translations:

   msgid "Hello, {name}!"
   msgstr "こんにちは、{name}さん！"
   
   msgid "You have {taskCount} tasks today"
   msgstr "今日のタスクは{taskCount}件です"
   
   msgid "Switch language"
   msgstr "言語を切り替え"

7. Compile and load messages

   Run npm run i18n:compile to generate optimized JS modules, then update App.tsx to load them:

   import { I18nProvider, useI18n, t } from '@fluenti/react'
   import en from './locales/compiled/en'
   import ja from './locales/compiled/ja'
   
   function TaskApp() {
     const { setLocale, locale } = useI18n()
     return (
       <div>
         <h1>{t`Hello, ${'Alice'}!`}</h1>
         <p>{t`You have ${3} tasks today`}</p>
         <button onClick={() => setLocale(locale === 'en' ? 'ja' : 'en')}>
           {t`Switch language`}
         </button>
       </div>
     )
   }
   
   export default function App() {
     return (
       <I18nProvider locale="en" fallbackLocale="en" messages={{ en, ja }}>
         <TaskApp />
       </I18nProvider>
     )
   }

8. Run

   npm run dev

   Open your browser and click “Switch language” to see the translations in action.

Next steps

• Message Format — plurals, selects, and ICU syntax
• Code Splitting — lazy-load translations per locale
• Best Practices — production patterns