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

Welcome

- 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

``bash
npm install next-i18n-auto
`

Quick Start

$3

Create .env.local in your project root:

`env
LIBRETRANSLATE_API_KEY=your_api_key_here
`

Get a free API key from LibreTranslate.

$3

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"
`

$3

`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 (



);
}
`

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 URL

API 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 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_KEY in .env.local
- Verify locales/ copied to public/locales/
- Check postbuild script ran successfully

Text not extracted:
- Ensure text is directly in JSX
- Check files are in scanned directories
- Verify .tsx or .jsx` extension

License

MIT

Contributing

Contributions welcome! Open an issue or PR on GitHub.