next-localization
The minimalistic localization solution for Next.js, powered by Rosetta and Next.js 10 Internationalized Routing.
✨ Features
- Supports all rendering modes: (Static) | ● (SSG) | λ (Server).
- Ideal companion to Next.js 10 Internationalized Routing
- Less than 1000 bytes – including dependencies!
- Pluralization support
- No build step, No enforced conventions.
Table of Contents
- Installation & Setup
- Basic Usage
- Usage with
getStaticProps - Redirect to default language
- Construct correct links
- Internationalization
- Access i18n outside React
- Performance considerations
- Other considerations
Installation & Setup
yarn add next-localization
Example
See example for full example and locale setup.
Basic Usage
Your _app.js.
import { I18nProvider } from 'next-localization';
import { useRouter } from 'next/router';
export default function MyApp({ Component, pageProps }) {
const router = useRouter();
const { lngDict, ...rest } = pageProps;
return (
<I18nProvider lngDict={lngDict} locale={router.locale}>
<Component {...rest} />
</I18nProvider>
);
}Any functional component.
import { useI18n } from 'next-localization';
import { useRouter } from 'next/router';
import Link from 'next/link';
const HomePage = () => {
const router = useRouter();
const i18n = useI18n();
// or
const i18nPlural = i18n.withPlural();
return (
<>
<h1>
{i18n.t('title')}}, {i18n.t('welcome', { username })}
</h1>
<p>{i18nPlural('products_count', { items: 2 })}</p>
<Link href="/" locale="en">
<a>Change language to (en)</a>
</Link>
</>
);
};
Usage with getStaticProps
Checkout the full example.
The same steps works with getServerSideProps.
Redirect to default language
Built-in with Next.js 10 Internationalized Routing
Construct correct links
Built-in with Next.js 10 Internationalized Routing
Internationalization
We rely on the native platform api Intl. If you need to support older browsers (e.g IE11) use polyfills.
Pluralization
We provide a small pluralization i18n.withPlural utility function. It returns the same ì18n interface but handles number values as pluralization. The implementation uses Intl.PluralRules.
import { useRouter } from 'next/router';
import { I18nProvider, useI18n } from 'next-localization';
function Root() {
const router = useRouter();
return (
<I18nProvider
lngDict={{
warning: 'WARNING: {{birds}}',
birds: {
other: 'birds',
one: 'bird',
two: 'two birds',
few: 'some birds'
}
}}
locale={router.locale}>
<Child />
</I18nProvider>
);
}
function Child() {
const i18n = useI18n();
const router = useRouter();
const t = i18n.withPlural();
return <p>{t('warning', { birds: 2 })}</p>; // WARNING: two birds
}Datetime, Numbers
Use DateTimeFormat, NumberFormat directly or rely on an external library. The integration will look very similiar.
import { useRouter } from 'next/router';
import { I18nProvider } from 'next-localization';
function Root() {
return (
<I18nProvider
lngDict={{
copyright: 'Copyright: {{date}}'
}}
locale={'en'}>
<Child />
</I18nProvider>
);
}
function Child() {
const router = useRouter();
const date = new Intl.DateTimeFormat(router.locale).format(new Date());
return <p>{t('copyright', { date })}</p>; // Copyright: 8/30/2020
}Access i18n outside React
If you need access to the i18n outside of react or react hooks, you can create a custom i18n instance and pass it to the I18nProvider.
It's the same interface as useI18n returns.
import { I18nProvider } from 'next-localization';
import { useRouter } from 'next/router';
const i18n = I18n({
en: { hello: 'Hello, world!' }
});
export default function MyApp({ Component, pageProps }) {
const router = useRouter();
const { lngDict, ...rest } = pageProps;
return (
<I18nProvider i18nInstance={i18n} lngDict={lngDict} locale={router.locale}>
<Component {...rest} />
</I18nProvider>
);
}Performance considerations
Don't forget that a locale change will rerender all components under the I18nProvider provider.
It's safe to create multiple providers with different language dictionaries. This can be useful if you want to split it into different namespaces.
Here you can see an example how to lazy-load a component with a different locale file. Code splitting is ensured by embedding the JSON file via the babel macro json.macro.
Other considerations
Depending on your application next-localization might not be sufficient to internationalize your application. You still need to consider:
With some effort those points are very easy to solve and you can still base on a very lightweight localization strategy.