README.md

next-localization

The minimalistic localization solution for Next.js, powered by Rosetta
and Next.js 10 Internationalized Routing.

---

Note: Are you looking for the next generation API Developer Platform? 🔎 Have a look at: WunderGraph Turn your services, databases and 3rd party APIs into a secure unified API in just a few minutes. 🪄

---

✨ 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
  • Pluralization
  • Datetime, Numbers
• 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:

• Format times and numbers.

With some effort those points are very easy to solve and you can still base on a very lightweight localization strategy.