next-lang
Docs
/
Introduction

Introduction

Welcome to the next-lang docs! Learn how to install, set up, and use next-lang in your React or Next.js projects.

Installation

Install next-lang using your preferred package manager:

npm install next-lang

Quick Start

Follow these steps to get started with next-lang:

1. Create your translations file

First, create a file to store your translations:

// translations.ts
export const translations = {
  en: {
    welcome: "Welcome to our app",
    about: "About us",
    contact: "Contact"
  },
  es: {
    welcome: "Bienvenido a nuestra aplicación",
    about: "Sobre nosotros",
    contact: "Contacto"
  }
}

2. Set up the LangProvider

Wrap your application with the LangProvider component:

// app/layout.tsx or _app.tsx
import { LangProvider } from 'next-lang'
import { translations } from './translations'

export default function RootLayout({ children }) {
  return (
    <LangProvider translations={translations} defaultLang="en">
      {children}
    </LangProvider>
  )
}

3. Use translations in your components

Now you can use the useLang hook to access your translations:

// components/Header.tsx
import { useLang } from 'next-lang'

export default function Header() {
  const { t, currentLang, setLang, toggleLang } = useLang()
  
  return (
    <header>
      <h1>{t('welcome')}</h1>
      <nav>
        <a href="/about">{t('about')}</a>
        <a href="/contact">{t('contact')}</a>
      </nav>
      <button onClick={() => toggleLang()}>
        Current: {currentLang}
      </button>
    </header>
  )
}

API Reference

LangProvider

The LangProvider component provides the language context to your application.

Props:

  • translations: An object containing all your translations
  • defaultLang: The default language to use
  • persistLang: (Optional) Whether to persist the language in localStorage (default: true)

useLang Hook

The useLang hook provides access to translations and language control functions.

Returns:

  • t: Function to get a translation by key
  • currentLang: The current language code
  • setLang: Function to set the language
  • toggleLang: Function to toggle between available languages
  • availableLangs: Array of available language codes

Advanced Usage

Nested Translations

You can use nested objects for more complex translation structures:

// translations.ts
export const translations = {
  en: {
    home: {
      title: "Welcome to our app",
      subtitle: "The best app for your needs"
    },
    about: {
      title: "About us",
      description: "We are a team of developers"
    }
  },
  es: {
    home: {
      title: "Bienvenido a nuestra aplicación",
      subtitle: "La mejor aplicación para tus necesidades"
    },
    about: {
      title: "Sobre nosotros",
      description: "Somos un equipo de desarrolladores"
    }
  }
}

Then access nested translations using dot notation:

const { t } = useLang()

// Access nested translations
<h1>{t('home.title')}</h1>
<p>{t('home.subtitle')}</p>

Language Persistence

By default, next-lang persists the selected language in localStorage. You can disable this behavior:

<LangProvider 
  translations={translations} 
  defaultLang="en"
  persistLang={false}
>
  {children}
</LangProvider>