next-i18n-auto
v1.0.1
Published
Automatic multilingual support for Next.js projects without manual text wrapping
Downloads
183
Maintainers
royalmelonReadme
next-i18n-auto
Automatic multilingual support for Next.js projects without manual text wrapping or translation functions.
Features
- Zero Code Changes: Write normal JSX like
<h1>Welcome</h1>- no wrapping or translation functions needed - 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
Installation
npm install next-i18n-autoQuick Start
1. Add LibreTranslate API Key
Create .env.local in your project root:
LIBRETRANSLATE_API_KEY=your_api_key_hereGet a free API key from LibreTranslate.
2. Add Postbuild Script
In your package.json:
{
"scripts": {
"build": "next build",
"postbuild": "next-i18n-auto --languages fr,es,de && cp -r locales public/"
}
}Windows users, use:
"postbuild": "next-i18n-auto --languages fr,es,de && xcopy /E /I locales public\locales"3. Initialize in Your App
'use client';
import { useEffect } from 'react';
import { initializeI18n } from 'next-i18n-auto/client';
export default function RootLayout({ children }) {
useEffect(() => {
initializeI18n({ defaultLanguage: 'en' });
}, []);
return <html><body>{children}</body></html>;
}4. Create Language Switcher
'use client';
import { useLanguage } from 'next-i18n-auto/client';
export default function LanguageSwitcher() {
const { language, switchLanguage, isLoading } = useLanguage();
return (
<div>
<button onClick={() => switchLanguage('en')} disabled={isLoading}>
English
</button>
<button onClick={() => switchLanguage('fr')} disabled={isLoading}>
Français
</button>
</div>
);
}5. Write Normal JSX
export default function Hero() {
return (
<div>
<h1>Welcome to our website</h1>
<p>We provide amazing services</p>
<button>Get Started</button>
</div>
);
}After build, this becomes:
<h1 data-i18n="hero_a3c5f1d2">Welcome to our website</h1>CLI Options
next-i18n-auto [options]--languages <codes>- Target language codes (required)--source <code>- Source language (default: en)--output <dir>- Output directory (default: locales)--root <dir>- Project root directory--api-url <url>- Custom LibreTranslate API URL
API Reference
React Hooks
import { useLanguage, usePreloadLanguages } from 'next-i18n-auto/client';
const { language, switchLanguage, isLoading } = useLanguage();
usePreloadLanguages(['fr', 'es', 'de']);Vanilla JavaScript
import { initializeI18n, switchLanguage, getCurrentLanguage } from 'next-i18n-auto/client';
await initializeI18n({ localesPath: '/locales' });
await switchLanguage('fr');
const lang = getCurrentLanguage();How It Works
Build Time
- Scans JSX/TSX files in your project
- Extracts all text nodes
- Generates unique IDs (e.g.,
componentName_hash) - Adds
data-i18nattributes automatically - Translates texts using LibreTranslate
- Creates JSON files per language
Runtime
- Loads selected language JSON
- Finds elements with
data-i18nattributes - Updates text content
- Persists selection in localStorage
Documentation
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_KEYin.env.local - Verify
locales/copied topublic/locales/ - Check postbuild script ran successfully
Text not extracted:
- Ensure text is directly in JSX
- Check files are in scanned directories
- Verify
.tsxor.jsxextension
License
MIT
Contributing
Contributions welcome! Open an issue or PR on GitHub.