Internationalization

Comprehensive guide to internationalizing your calendar with custom translations, locales, and formatting.

Overview

The calendar supports comprehensive internationalization through multiple approaches: locale-based formatting, custom translations object, or translator functions. If both translations and translator are provided, the translator function takes priority.

Basic Locale Setup

The simplest way to internationalize your calendar is by setting the locale and timezone props. This will automatically format dates according to the specified locale. 

import { IlamyCalendar } from '@ilamy/calendar';

function InternationalCalendar() {
  return (
    <IlamyCalendar
      events={events}
      locale="fr" // French locale for date formatting
      timezone="Europe/Paris" // Paris timezone
      firstDayOfWeek="monday"
    />
  );
}

Custom Translations

For more control over the text displayed in your calendar, you can provide a custom translations object. This allows you to translate button labels, view names, and other UI text. 

import { IlamyCalendar } from '@ilamy/calendar';

const frenchTranslations = {
  today: 'Aujourd\'hui',
  month: 'Mois',
  week: 'Semaine',
  day: 'Jour',
  year: 'Année',
  previous: 'Précédent',
  next: 'Suivant',
  // Add more translation keys as needed
};

function TranslatedCalendar() {
  return (
    <IlamyCalendar
      events={events}
      locale="fr"
      translations={frenchTranslations}
      firstDayOfWeek="monday"
    />
  );
}

Translator Function

For dynamic translations or integration with existing i18n libraries, you can provide a translator function. This function receives a translation key and optional parameters, and should return the translated string. 

import { IlamyCalendar } from '@ilamy/calendar';

function TranslatorCalendar() {
  const translator = (key, options) => {
    const translations = {
      today: 'Aujourd\'hui',
      month: 'Mois',
      week: 'Semaine',
      day: 'Jour',
      year: 'Année',
      previous: 'Précédent',
      next: 'Suivant',
    };
    
    // Handle dynamic translations based on options
    if (options && options.count) {
      // Pluralization logic
      if (key === 'events') {
        return options.count === 1 ? 'événement' : 'événements';
      }
    }
    
    return translations[key] || key;
  };

  return (
    <IlamyCalendar
      events={events}
      locale="fr"
      translator={translator}
      firstDayOfWeek="monday"
    />
  );
}

Integration with i18n Libraries

You can easily integrate the calendar with popular i18n libraries like react-i18next, react-intl, or others. 

import { IlamyCalendar } from '@ilamy/calendar';
import { useTranslation } from 'react-i18next';

function I18nCalendar() {
  const { t, i18n } = useTranslation();

  const translator = (key, options) => {
    return t(`calendar.${key}`, options);
  };

  return (
    <IlamyCalendar
      events={events}
      locale={i18n.language}
      translator={translator}
      firstDayOfWeek="monday"
    />
  );
}
import { IlamyCalendar } from '@ilamy/calendar';
import { useIntl } from 'react-intl';

function IntlCalendar() {
  const intl = useIntl();

  const translator = (key, options) => {
    return intl.formatMessage(
      { id: `calendar.${key}` },
      options
    );
  };

  return (
    <IlamyCalendar
      events={events}
      locale={intl.locale}
      translator={translator}
      firstDayOfWeek="monday"
    />
  );
}

Available Translation Keys

The calendar supports a comprehensive set of translation keys for all UI elements including common actions, event properties, recurrence options, view types, days of the week, and months. You can find the complete list of available keys via the TranslationKey type which is exported from the calendar package. 

import { TranslationKey } from '@ilamy/calendar';

// The TranslationKey type includes all available keys:
// - Common actions: today, create, update, delete, cancel
// - Event related: event, events, title, description, location, etc.
// - Recurrence: repeat, daily, weekly, monthly, yearly, etc.
// - View types: month, week, day, year
// - Days of week: sunday, monday, tuesday, etc.
// - Months: january, february, march, etc.

const myTranslator = (key: TranslationKey) => {
  // Your translation logic here
  return translations[key] || key;
};

Types

TypeScript type definitions for internationalization features. 

// Translations object interface (simplified - see TranslationKey for complete list)
interface Translations {
  today: string;
  month: string;
  week: string;
  day: string;
  year: string;
  // ... many more keys (see TranslationKey type)
}

// Translation key type (exported from package)
type TranslationKey = keyof Translations;

// Translator function type
type TranslatorFunction = (key: TranslationKey | string) => string;

// Example usage
const frenchTranslations: Translations = {
  today: 'Aujourd\'hui',
  month: 'Mois',
  week: 'Semaine',
  day: 'Jour',
  year: 'Année',
  // ... complete all required keys
};

const dynamicTranslator: TranslatorFunction = (key) => {
  // Custom translation logic
  return getTranslation(key);
};

Best Practices

Priority Order

When both translations and translator are provided, the translator function takes priority. Use this to your advantage:

  • Provide fallback translations with the translations prop
  • Use translator for dynamic or complex translation logic
  • The translator can fall back to the static translations when needed

Performance

  • Memoize your translator function to avoid unnecessary re-renders
  • Use static translations objects when possible for better performance
  • Consider lazy loading translations for large applications

Locale Setup

  • Always set the locale prop for proper date formatting
  • Consider setting firstDayOfWeek based on locale conventions
  • Use appropriate timezone settings for your users' locations
iCalendar ExportStyling