Localization Guide

Learn how to translate and localize your FullEventCalendar to support multiple languages and regional preferences.

Overview

FullEventCalendar comes with built-in localization support, allowing you to:

Translate the user interface
Format dates according to regional preferences
Toggle between 12-hour and 24-hour time formats

Supported Languages

Out of the box, FullEventCalendar supports the following languages:

English (en) - Default
Spanish (es)
French (fr)
Danish (da)
Norwegian (nb)
Portuguese (pt)
Swedish (sv)
"L33t speak" (l33t) - Fun easter egg language

Configuring the Language

To change the calendar's language, provide the localization property in the config object:

import { EventCalendar } from '@/components/event-calendar';
import { spanishTranslations } from '@/components/event-calendar/locales/es';

const MyCalendar = () => {
  return (
    <EventCalendar
      config={{
        localization: spanishTranslations
      }}
      // ...other props
    />
  );
};

Localization Structure

The localization system is based on the EventCalendarTranslations interface:

interface EventCalendarTranslations {
  // Date formatting
  months: string[];
  monthsShort: string[];
  weekdays: string[];
  weekdaysShort: string[];
  
  // Calendar navigation
  today: string;
  viewDay: string;
  viewWeek: string;
  viewMonth: string;
  viewYear: string;
  viewList: string;
  
  // Event management
  newEvent: string;
  editEvent: string;
  deleteEvent: string;
  deleteEventConfirmation: string;
  deleteEventConfirmationDescription: string;
  cancel: string;
  save: string;
  untitled: string;
  allDay: string;
  
  // Form labels
  eventName: string;
  eventDescription: string;
  eventColor: string;
  startDate: string;
  endDate: string;
  startTime: string;
  endTime: string;
  repeat: string;
  daily: string;
  weekly: string;
  monthly: string;
  
  // List view
  searchEvents: string;
  noEvents: string;
  noSearchResults: string;
  
  // Validation messages
  validations: {
    eventNameRequired: string;
    colorRequired: string;
    endTimeBeforeStart: string;
    invalidTimeFormat: string;
  };
}

Creating a Custom Localization

To create a new language translation, create a new file in the locales directory:

// locales/de.ts (German example)
import { EventCalendarTranslations } from "../types/EventCalendarTranslations";

export const germanTranslations: EventCalendarTranslations = {
  // Date formatting
  months: [
    "Januar", "Februar", "März", "April", "Mai", "Juni",
    "Juli", "August", "September", "Oktober", "November", "Dezember"
  ],
  monthsShort: [
    "Jan", "Feb", "Mär", "Apr", "Mai", "Jun",
    "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"
  ],
  weekdays: [
    "Sonntag", "Montag", "Dienstag", "Mittwoch",
    "Donnerstag", "Freitag", "Samstag"
  ],
  weekdaysShort: ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"],
  
  // Calendar navigation
  today: "Heute",
  viewDay: "Tag",
  viewWeek: "Woche",
  viewMonth: "Monat",
  viewYear: "Jahr",
  viewList: "Liste",
  
  // Event management
  newEvent: "Neuer Termin",
  editEvent: "Termin bearbeiten",
  deleteEvent: "Termin löschen",
  deleteEventConfirmation: "Termin löschen?",
  deleteEventConfirmationDescription: "Diese Aktion kann nicht rückgängig gemacht werden.",
  cancel: "Abbrechen",
  save: "Speichern",
  untitled: "Ohne Titel",
  allDay: "Ganztägig",
  
  // Form labels
  eventName: "Terminname",
  eventDescription: "Beschreibung",
  eventColor: "Farbe",
  startDate: "Startdatum",
  endDate: "Enddatum",
  startTime: "Startzeit",
  endTime: "Endzeit",
  repeat: "Wiederholen",
  daily: "Täglich",
  weekly: "Wöchentlich",
  monthly: "Monatlich",
  
  // List view
  searchEvents: "Termine suchen",
  noEvents: "Keine Termine",
  noSearchResults: "Keine Ergebnisse gefunden",
  
  // Validation messages
  validations: {
    eventNameRequired: "Terminname ist erforderlich",
    colorRequired: "Farbe ist erforderlich",
    endTimeBeforeStart: "Endzeit muss nach Startzeit liegen",
    invalidTimeFormat: "Ungültiges Zeitformat (HH:MM)",
  },
};

Language Detection

The calendar does not automatically detect the user's language. You need to:

Determine the user's preferred language (e.g., from browser settings, user preferences)
Import the appropriate translation file
Pass it to the calendar via the config.localization prop

Example with dynamic language selection:

import { useState, useEffect } from 'react';
import { EventCalendar } from '@/components/event-calendar';
import { englishTranslations } from '@/components/event-calendar/locales/en';
import { spanishTranslations } from '@/components/event-calendar/locales/es';
import { frenchTranslations } from '@/components/event-calendar/locales/fr';

const languageMap = {
  'en': englishTranslations,
  'es': spanishTranslations,
  'fr': frenchTranslations,
};

const MyCalendar = () => {
  const [language, setLanguage] = useState('en');
  
  return (
    <div>
      <select 
        value={language} 
        onChange={(e) => setLanguage(e.target.value)}
      >
        <option value="en">English</option>
        <option value="es">Español</option>
        <option value="fr">Français</option>
      </select>
      
      <EventCalendar
        config={{
          localization: languageMap[language]
        }}
        // ...other props
      />
    </div>
  );
};

Time Format Localization

FullEventCalendar supports both 12-hour and 24-hour time formats. This can be configured globally and users can toggle between formats.

Default Time Format

Set the default time format in the config:

const config = {
  use24HourFormatByDefault: true,  // Use 24-hour format (14:00)
  // or
  use24HourFormatByDefault: false, // Use 12-hour format (2:00 PM)
};

User Toggle

The calendar header includes a button to toggle between time formats. This state is managed internally and persists during the user's session.

RTL (Right-to-Left) Support

For RTL languages like Arabic, Hebrew, or Persian, you need to:

Set the dir="rtl" attribute on your HTML element
Use a Tailwind CSS RTL plugin or custom RTL styles
Create a localization file for the RTL language

The calendar will respect the document's text direction.

Handling Special Cases

Date and Time Formatting

Date and time formatting uses the built-in JavaScript Date methods. For more complex formatting needs, you may need to extend the calendar with a library like date-fns or Intl API.

Plural Forms

Different languages handle plurals differently. If your language has complex plural rules, you may need to modify the way certain strings are displayed.

Testing Localization

To test your localizations:

Create a test page that switches between different languages
Verify that all UI elements are properly translated
Check date formatting and time displays
Test with longer text to ensure the layout accommodates longer translations

Performance Considerations

Localization doesn't significantly impact performance, but keep in mind:

Import only the languages you need to reduce bundle size
Consider dynamic imports for on-demand loading of language files

Conclusion

FullEventCalendar's localization system makes it easy to create a multilingual calendar experience. By providing translations and configuring time formats, you can make your calendar accessible to users from different regions and language backgrounds.