Advanced Usage
SSR Configuration
The plugin fully supports server-side rendering (SSR) scenarios.
Server-side Language Detection
In SSR scenarios, the plugin will detect language from HTTP requests:
- URL Path: Extract language prefix from path
- Cookie: Read language settings from cookies
- Request Headers: Read from
Accept-Languagerequest header
Configuration Example:
i18nPlugin({
localeDetection: {
localePathRedirect: true,
i18nextDetector: true,
languages: ['zh', 'en'],
fallbackLanguage: 'en',
detection: {
order: ['path', 'cookie', 'header'],
lookupHeader: 'accept-language',
},
},
})SSR Resource Loading
In SSR scenarios, the plugin will automatically use the file system backend to load resources:
export default defineConfig({
server: {
ssr: true,
publicDir: './locales', // Resource file directory
},
plugins: [
i18nPlugin({
backend: {
enabled: true,
},
}),
],
});Resource file structure:
Project Root/
└── locales/
├── en/
│ └── translation.json
└── zh/
└── translation.jsonMulti-Entry Configuration
If the project has multiple entries, you can configure language detection and backend options separately for each entry.
Configure Language Detection by Entry
i18nPlugin({
localeDetection: {
// Global configuration
localePathRedirect: true,
languages: ['zh', 'en'],
fallbackLanguage: 'en',
// Override configuration by entry
localeDetectionByEntry: {
admin: {
localePathRedirect: false, // admin entry does not use path redirection
languages: ['en'], // admin entry only supports English
},
mobile: {
languages: ['zh', 'en', 'ja'], // mobile entry supports more languages
},
},
},
})Configure Backend by Entry
i18nPlugin({
backend: {
enabled: true,
loadPath: '/locales/{{lng}}/{{ns}}.json', // Default path
// Override configuration by entry
backendOptionsByEntry: {
admin: {
loadPath: '/admin/locales/{{lng}}/{{ns}}.json',
},
mobile: {
loadPath: '/mobile/locales/{{lng}}/{{ns}}.json',
},
},
},
})Custom i18next Instance
If you need to use a custom i18next instance, you can provide it in runtime configuration.
Create Custom Instance
// src/i18n.ts
import i18next from 'i18next';
const customI18n = i18next.createInstance({
// Custom configuration
fallbackLng: 'en',
supportedLngs: ['zh', 'en'],
interpolation: {
escapeValue: false,
},
});
export default customI18n;Pass Custom Instance
// src/modern.runtime.ts
import { defineRuntimeConfig } from '@modern-js/runtime';
import customI18n from './i18n';
export default defineRuntimeConfig({
i18n: {
i18nInstance: customI18n,
initOptions: {
// Other configuration options
},
},
});Language Switching
Programmatic Switching
Use the changeLanguage method of the useModernI18n Hook:
import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
function LanguageSwitcher() {
const { language, changeLanguage, supportedLanguages } = useModernI18n();
return (
<select
value={language}
onChange={e => changeLanguage(e.target.value)}
>
{supportedLanguages.map(lang => (
<option key={lang} value={lang}>
{lang}
</option>
))}
</select>
);
}URL Synchronization
When localePathRedirect is enabled, switching languages will automatically update the URL:
// Current URL: /en/about
// Call changeLanguage('zh')
// URL automatically updates to: /zh/aboutIf localePathRedirect is not enabled, language switching will only update the i18next instance and cache, without changing the URL.