Skip to main content

🌍 How to Translate JetShip in Your Own Language?

· 3 min read

The JetShip Next.js Starter Kit comes with built-in internationalization (i18n) support using the powerful i18next library. This guide will walk you through the process of translating the starter kit 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 starter kit 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 starter kit 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 starter kit 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 starter kit 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 Starter Kit 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.