SupaStart
Getting Started

Internationalization (i18n)

Learn how Supastart handles internationalization (i18n) with built-in configuration, language settings, translation files, and formatting utilities.

Overview

Supastart offers integrated support for internationalization (i18n), enabling your application to display locale-specific content—including formatted dates, times, and currencies—while also facilitating language management and time zone support.

Implementation Architecture

Supastart implements i18n using the following components:

  1. i18next Integration - Using the popular i18next library for translations
  2. Language Provider - React context for managing language state
  3. Formatting Utilities - Helper functions for date, time, and currency formatting
  4. Translation Files - JSON-based locale files for each supported language
  5. DirectionProvider - For RTL language support

Configuration

i18next Configuration

The core i18n configuration is set up in src/app/i18n.ts, which initializes i18next with all available translations:

import arTranslation from '@/i18n/messages/ar.json';
import chTranslation from '@/i18n/messages/ch.json';
import deTranslation from '@/i18n/messages/de.json';
import enTranslation from '@/i18n/messages/en.json';
import esTranslation from '@/i18n/messages/es.json';
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
 
i18n.use(initReactI18next).init({
  resources: {
    en: { translation: enTranslation },
    ar: { translation: arTranslation },
    de: { translation: deTranslation },
    es: { translation: esTranslation },
    ch: { translation: chTranslation },
  },
  lng: 'en',
  fallbackLng: 'en',
  interpolation: {
    escapeValue: false,
  },
});
 
export default i18n;

Language Provider

The I18nProvider component manages language selection and persistence:

function I18nProvider({ children, initialLanguage }: I18nProviderProps) {
  const [languageCode, setLanguageCode] = useState<string>(() => {
    // If initialLanguage is provided, use it
    if (initialLanguage) {
      return initialLanguage;
    }
 
    // Otherwise try to get from localStorage
    if (typeof window !== 'undefined') {
      return localStorage.getItem('language') || 'en';
    }
    return 'en'; // Default language if running on the server
  });
 
  // Find the current language configuration based on the language code
  const language =
    languages.find((lang) => lang.code === languageCode) || languages[0];
 
  useEffect(() => {
    if (typeof window !== 'undefined') {
      localStorage.setItem('language', languageCode);
    }
    if (language?.direction) {
      document.documentElement.setAttribute('dir', language.direction);
    }
    i18n.changeLanguage(languageCode);
  }, [languageCode, language]);
 
  const changeLanguage = (code: string) => {
    setLanguageCode(code);
    if (typeof window !== 'undefined') {
      localStorage.setItem('language', code);
    }
  };
 
  return (
    <LanguageContext.Provider
      value={{ languageCode, changeLanguage, language }}
    >
      {children}
    </LanguageContext.Provider>
  );
}

Direction Provider

For RTL support, Supastart includes a DirectionProvider that leverages Radix UI's direction context:

// src/providers/direction-provider.tsx
'use client';
 
import { DirectionProvider as RadixDirectionProvider } from '@radix-ui/react-direction';
import { useLanguage } from './i18n-provider';
 
const DirectionProvider = ({ children }: { children: React.ReactNode }) => {
  const { language } = useLanguage();
 
  return (
    <RadixDirectionProvider dir={language.direction}>
      {children}
    </RadixDirectionProvider>
  );
};

Language Settings

The language settings are established in src/i18n/config.ts. This file defines the metadata for each supported language, including its code, display name, text direction, and corresponding flag icon.

export interface Language {
	code: string;
	name: string;
	shortName: string;
	direction: 'ltr' | 'rtl';
	flag: string;
}
 
export const languages: Language[] = [
	{
		code: 'en',
		name: 'English',
		shortName: 'EN',
		direction: 'ltr',
		flag: '/media/flags/united-states.svg',
	},
	{
		code: 'ar',
		name: 'Arabic',
		shortName: 'AR',
		direction: 'rtl',
		flag: '/media/flags/saudi-arabia.svg',
	},
	{
		code: 'es',
		name: 'Spanish',
		shortName: 'ES',
		direction: 'ltr',
		flag: '/media/flags/spain.svg',
	},
	{
		code: 'de',
		name: 'German',
		shortName: 'DE',
		direction: 'ltr',
		flag: '/media/flags/germany.svg',
	},
	{
		code: 'ch',
		name: 'Chinese',
		shortName: 'CH',
		direction: 'ltr',
		flag: '/media/flags/china.svg',
	},
];

Translation Files

Translation strings are stored as JSON files in the src/i18n/messages folder. Each file corresponds to a specific locale.

English Translations Example

{
  "common": {
    "enums": {
      "category_status": {
        "active": "Active",
        "inactive": "Inactive"
      }
    },
    "messages": {
      "unauthorized": "Unauthorized access.",
      "system_error": "Oops! Something didn't go as planned. Please try again in a moment.",
      "invalid_input": "Invalid input. Please check your data and try again.",
      "data_not_found": "Requested data not found.",
      "delete_restricted_error": "Unable to delete this record because it is linked to other records."
    },
    "confirm-dimiss-dialog": {
      "title": "Discard changes?",
      "description": "You have unsaved changes. Are you sure you want to close this dialog?",
      "cancel": "Cancel",
      "confirm": "Discard changes"
    },
    "logout": "Logout",
    "footer": "© 2025 Supastart. All rights reserved."
  },
  "login": {
    "title": "Login",
    "subtitle": "Enter your credentials to access your account",
    "email": "Email",
    "password": "Password",
    "remember_me": "Remember me",
    "forgot_password": "Forgot password?",
    "sign_in": "Sign In",
    "create_account": "Don't have an account? Create one"
  },
  "dashboard": {
    "title": "Dashboard",
    "welcome": "Welcome to Supastart",
    "description": "This is a localized dashboard with RTL support. Try changing the language to Arabic to see RTL in action."
  }
}

Using Translations in Components

Within your React components, use the useTranslation hook from react-i18next to access localized strings:

import { useTranslation } from 'react-i18next';
 
const MyComponent = () => {
  const { t } = useTranslation();
 
  return (
    <div>
      <h1>{t('login.title')}</h1>
      <p>{t('common.messages.system_error')}</p>
      <button>{t('login.sign_in')}</button>
    </div>
  );
};
 
export default MyComponent;

Language Switching

The language can be changed using the useLanguage hook:

import { useLanguage } from '@/providers';
 
function LanguageSwitcher() {
  const { languageCode, changeLanguage, language } = useLanguage();
 
  return (
    <div>
      <span>Current Language: {language.name}</span>
      <select
        value={languageCode}
        onChange={(e) => changeLanguage(e.target.value)}
      >
        {languages.map((lang) => (
          <option key={lang.code} value={lang.code}>
            {lang.name}
          </option>
        ))}
      </select>
    </div>
  );
}

RTL Support

Arabic language is supported with right-to-left (RTL) text direction. The language provider automatically sets the dir attribute on the document root element:

useEffect(() => {
  if (language?.direction) {
    document.documentElement.setAttribute('dir', language.direction);
  }
}, [language]);

Components that need special RTL handling use Tailwind's RTL variant:

<ChevronRight className="rtl:rotate-180" />
 
<th
  className={cn(
    'h-12 px-4 text-left rtl:text-right align-middle font-normal text-muted-foreground',
    className,
  )}
/>

Formatting Utilities

Supastart provides utility functions for localized formatting of dates, times, and currencies in src/i18n/format.ts.

Date and Time Formatting

// Format a date to "Dec 7, 2024" format
export const formatDate = (date: Date | string): string => {
  const locale = getCurrentLocale();
  const parsedDate = typeof date === 'string' ? new Date(date) : date;
  return new Intl.DateTimeFormat(locale, {
    year: 'numeric',
    month: 'short',
    day: 'numeric',
  }).format(parsedDate);
};
 
// Format a date and time to "Dec 7, 2024, 11:41 PM" format
export const formatDateTime = (date: Date | string): string => {
  const locale = getCurrentLocale();
  const parsedDate = typeof date === 'string' ? new Date(date) : date;
  return new Intl.DateTimeFormat(locale, {
    year: 'numeric',
    month: 'short',
    day: 'numeric',
    hour: 'numeric',
    minute: 'numeric',
    hour12: true,
  }).format(parsedDate);
};
 
// Format time to "11:41 PM" format
export const formatTime = (date: Date | string): string => {
  const locale = getCurrentLocale();
  const parsedDate = typeof date === 'string' ? new Date(date) : date;
  return new Intl.DateTimeFormat(locale, {
    hour: 'numeric',
    minute: 'numeric',
    hour12: true,
  }).format(parsedDate);
};

Currency Formatting

// Format money to a localized currency string
export const formatMoney = (
  amount: number,
  currency: string = 'USD',
): string => {
  const locale = getCurrentLocale();
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
  }).format(amount);
};

Time Zones Utility

The helper in src/i18n/timezones.ts provides a sorted list of supported time zones:

export const getTimeZones = (): { label: string; value: string }[] => {
  // Fetch supported timezones
  const timezones = Intl.supportedValuesOf('timeZone');
 
  return timezones
    .map((timezone) => {
      const formatter = new Intl.DateTimeFormat('en', {
        timeZone: timezone,
        timeZoneName: 'shortOffset',
      });
      const parts = formatter.formatToParts(new Date());
      const offset =
        parts.find((part) => part.type === 'timeZoneName')?.value || '';
      const formattedOffset = offset === 'GMT' ? 'GMT+0' : offset;
 
      return {
        value: timezone,
        label: `(${formattedOffset}) ${timezone.replace(/_/g, ' ')}`,
        numericOffset: parseInt(
          formattedOffset.replace('GMT', '').replace('+', '') || '0',
        ),
      };
    })
    .sort((a, b) => a.numericOffset - b.numericOffset); // Sort by numeric offset
};
PreviousDeploymentNextRouting