The Jetship Next.js Boilerplate comes with built-in internationalization (i18n) support using the powerful i18next library. This guide will walk you through the process of translating the boilerplate into your preferred language.

Understanding the structure

The internationalization setup in Jetship follows a clean and organized structure:

apps/web/src/data/locales/
├── en/
│   └── translation.json
├── fr/
│   └── translation.json
└── de/
    └── translation.json

The boilerplate comes with three default languages: English (en), French (fr), and German (de). Each language has its own directory containing translation files organized by namespaces.

Namespaces in i18next

Namespaces are a way to organize your translations into logical groups. The boilerplate uses the following namespace structure:

• translation (default namespace): Contains general UI translations

• You can add more namespaces for specific features or sections of your app

• The namespace configuration is defined in i18n-settings.ts:

  export const defaultI18nNamespaces = ['translation']
  

Language Persistence

The boilerplate uses cookies to persist the user's language preference. This means:

• The selected language is saved in the browser
• When the user returns to your site, their language preference is automatically restored
• The language preference works across page refreshes and browser session

Steps to Add Your Language

1. Create a New Language Directory

• Navigate to apps/web/src/data/locales/
• Create a new directory with your language code (e.g., es for Spanish, it for Italian)
• Create a translation.json file inside this directory

2. Add Translation Keys

• Copy the content from en/translation.json

• Translate each value while keeping the keys unchanged

• Example

  {
    "welcome": "Welcome" // English
  }
  becomes
  {
    "welcome": "Bienvenido" // Spanish
  }
  

3. Register Your Language

• Open apps/web/src/lib/i18n/i18n-settings.ts
• Add your language code to the languages array
• The first language in the array serves as the fallback language

4. Adding New Namespaces (Optional)

• Create a new JSON file in each language directory with your namespace name

locales/
├── en/
│   ├── translation.json
│   └── dashboard.json    // New namespace
├── fr/
│   ├── translation.json
│   └── dashboard.json

• Add the namespace to defaultI18nNamespaces in i18n-settings.ts

Best Practices

1. Maintain Key Structure

• Keep the same key structure across all language files
• Use descriptive keys that reflect the content
• Group related translations using nested objects

2. Handle Dynamic Content

• Use placeholders for dynamic content: {{variable}}
• Keep the same placeholder names across all translations

3. Testing Translations

• Test your translations in development mode
• Check for missing translations
• Verify that dynamic content works correctly

Using Translations in Components

Using the Trans component to translate:

import Trans from '@repo/i18n/src/Trans'

const ComponentPage = () => {
  return (
    <div>
      <Trans i18nKey='welcome' />
    </div>
  )
}

export default ComponentPage

Using the useTranslation Hook:

import { useTranslation } from 'react-i18next'

const ComponentPage = () => {
  const { t } = useTranslation()

  return <div>{t('hello')}</div>
}

export default ComponentPage

Language Switching

The boilerplate includes a language switcher component that:

• Automatically detects the user's preferred language
• Allows manual language selection
• Persists the selection in cookies
• Provides immediate feedback when language is changed

Conclusion

Translating the Jetship Next.js Boilerplate is straightforward thanks to its well-organized i18n implementation. By following these steps, you can make your application accessible to users in multiple languages, expanding your global reach.