next-i18n-cookies v0.0.1

next-i18n-cookies

next-i18n-cookies is an internationalization (i18n) library for React/Next.js that enables localization in your applications using cookies to store the locale information. Unlike traditional i18n solutions that use path names to identify locales, next-i18n-cookies makes it seamless for your users to switch languages by persisting the locale preference in cookies.

It's compatible with React, Next.js, and any other framework that uses React.

Why did I create this?

I couldn't find a simple i18n solution for Next.js that didn't use path names to identify locales. I wanted to make it as easy as possible for my users to switch languages, and I didn't want to have to worry about adding language identifiers to my URL paths.

Also, I wanted to learn how to create a React library, and this seemed like a good opportunity to do so.

Roadmap

• Basic functionality (translations, cookies, etc.)
• Auto detect user's preferred locale based on their browser settings
• Documentation

Features

• Seamless i18n integration with Next.js and React applications
• Uses cookies to store the user's selected locale, ensuring a consistent experience across sessions
• Lightweight and easy to use, with a minimal configuration required
• No need to add language identifiers to your URL paths
• Compatible with server-side rendering (SSR) and client-side navigation
• Automatically detects the user's preferred locale based on their browser settings
• Different locales per each page

Installation

To get started with next-i18n-cookies, simply install it using npm or yarn:

npm install next-i18n-cookies
# or
yarn add next-i18n-cookies

Usage

1. Initialize the global context:

   // App.js or _app.js
   import { I18nCookiesProvider } from 'next-i18n-cookies'
   
   function MyApp({ Component, pageProps }) {
     return (
       <I18nCookiesProvider // <-- This is the provider for the translations - the current language context is stored in this context
         options={{
           locales: ['en', 'hr'], // <-- The list of supported locales - required
           defaultLocale: 'en', // <-- The default locale - not required (fallback is 'en')
         }}
       >
         <Component {...pageProps} />
       </I18nCookiesProvider>
     )
   }

2. Load your translations: (in this example, we're using JSON files and a locales directory)

   ├── locales
   │   ├── en.json
   │   └── hr.json

   en.json
   {
     "hello": "Hello, world!"
   }

   hr.json

   {
     "hello": "Pozdrav, svijete!"
   }

   // App.js
   import { loadTranslations, useTranslations } from 'next-i18n-cookies'
   
   // ...
   
   const Provider = loadTranslations({ // IMPORTANT: You can only have one provider per page (you can't nest providers)
     en: require('./locales/en.json'),
     hr: require('./locales/hr.json'),
   });
   
   // ...
   
   function Home() {
     return (
       <Provider> // <-- This is the provider for the translations
         <Content />
       </Provider>
     )
   }
   
   function Content() {
     const { t } = useTranslations() // <-- This is the hook for accessing the translations
   
     return (
       <div>
         <h1>{t('hello')}</h1>
       </div>
     )
   }

3. Use the provider in your _app.js file (or the layout.js file if you're using app directory):

   import { I18nCookiesProvider } from 'next-i18n-cookies'
   
   function MyApp({ Component, pageProps }) {
     return (
       <I18nCookiesProvider>
         <Component {...pageProps} />
       </I18nCookiesProvider>
     )
   }
   
   export default MyApp

4. Use it:

   import { useTranslations, useTranslationsCookiesContext } from 'next-i18n-cookies'
   
   function Home() {
     const { t } = useTranslations()
     const { locale, setLocale } = useTranslationsCookiesContext();
   
     return (
       <div>
         <h1>{t('hello')}</h1>
         <p>Current locale is: {locale}</p>
         <button onClick={() => setLocale('hr')}>Switch to Croatian</button>
       </div>
     )
   }
   
   export default Home

Examples

Different locales per each page

If you want to use different locales per each page, you can do so by using the loadTranslations function in each page:

// Home page

import { loadTranslations, useTranslations } from 'next-i18n-cookies'

const Provider = loadTranslations({
  en: require('../locales/home/en.json'),
  hr: require('../locales/home/hr.json'),
});

function Home() {
  const { t } = useTranslations();

  return (
    <Provider>
      <h1>{t('hello')}</h1>
    </Provider>
  )
}

// About page

import { loadTranslations, useTranslations } from 'next-i18n-cookies'

const Provider = loadTranslations({
  en: {
    another_page: 'Another page',
  },
  hr: {
    another_page: 'Druga stranica',
  },
});

function About() {
  const { t } = useTranslations();

  return (
    <Provider>
      <h1>{t('another_page')}</h1>
    </Provider>
  )
}