Automatic multilingual support for Next.js projects without manual text wrapping
npm install next-i18n-autoAutomatic multilingual support for Next.js projects without manual text wrapping or translation functions.
- Zero Code Changes: Write normal JSX like - no wrapping or translation functions neededWelcome
- Automatic Text Extraction: Scans your components and extracts all text nodes at build time
- Automatic Translation: Translates all text to target languages using LibreTranslate
- Runtime Language Switching: Switch languages dynamically in the browser
- Type-Safe: Full TypeScript support
- Simple Integration: Just add a postbuild script to your package.json
``bash`
npm install next-i18n-auto
Create .env.local in your project root:
`env`
LIBRETRANSLATE_API_KEY=your_api_key_here
Get a free API key from LibreTranslate.
In your package.json:
`json`
{
"scripts": {
"build": "next build",
"postbuild": "next-i18n-auto --languages fr,es,de && cp -r locales public/"
}
}
Windows users, use:
`json`
"postbuild": "next-i18n-auto --languages fr,es,de && xcopy /E /I locales public\locales"
`tsx
'use client';
import { useEffect } from 'react';
import { initializeI18n } from 'next-i18n-auto/client';
export default function RootLayout({ children }) {
useEffect(() => {
initializeI18n({ defaultLanguage: 'en' });
}, []);
return
{children};$3
`tsx
'use client';import { useLanguage } from 'next-i18n-auto/client';
export default function LanguageSwitcher() {
const { language, switchLanguage, isLoading } = useLanguage();
return (
);
}
`$3
`tsx
export default function Hero() {
return (
Welcome to our website
We provide amazing services
);
}
`After build, this becomes:
`tsx
Welcome to our website
`CLI Options
`bash
next-i18n-auto [options]
`-
--languages - Target language codes (required)
- --source - Source language (default: en)
- --output - Output directory (default: locales)
- --root - Project root directory
- --api-url - Custom LibreTranslate API URLAPI Reference
$3
`tsx
import { useLanguage, usePreloadLanguages } from 'next-i18n-auto/client';const { language, switchLanguage, isLoading } = useLanguage();
usePreloadLanguages(['fr', 'es', 'de']);
`$3
`typescript
import { initializeI18n, switchLanguage, getCurrentLanguage } from 'next-i18n-auto/client';await initializeI18n({ localesPath: '/locales' });
await switchLanguage('fr');
const lang = getCurrentLanguage();
`How It Works
$3
1. Scans JSX/TSX files in your project
2. Extracts all text nodes
3. Generates unique IDs (e.g., componentName_hash)
4. Adds data-i18n attributes automatically
5. Translates texts using LibreTranslate
6. Creates JSON files per language$3
1. Loads selected language JSON
2. Finds elements with data-i18n attributes
3. Updates text content
4. Persists selection in localStorageDocumentation
See DOCUMENTATION.md for detailed documentation.
See EXAMPLE.md for complete integration examples.
Supported Languages
Any language supported by LibreTranslate:
en, fr, es, de, it, pt, ru, zh, ja, ko, ar, and more...
Limitations
- Text must be directly in JSX (not in variables)
- Dynamic template strings with variables won't be translated
- Very short text (< 2 chars) is skipped
- Numbers/symbols-only text is skipped
Troubleshooting
Translations not working:
- Check
LIBRETRANSLATE_API_KEY in .env.local
- Verify locales/ copied to public/locales/
- Check postbuild script ran successfullyText not extracted:
- Ensure text is directly in JSX
- Check files are in scanned directories
- Verify
.tsx or .jsx` extensionLicense
MIT
Contributing
Contributions welcome! Open an issue or PR on GitHub.