Localization

Quick Start

Import a built-in locale and assign it to the component. The UI updates immediately.

import { useRef, useEffect } from 'react';
import { GanttChart, GanttChartRef, deLocale } from '@timelinekit/react';

export default function App() {
  const ref = useRef<GanttChartRef>(null);

  useEffect(() => {
    ref.current!.locale = deLocale;
  }, []);

  return <GanttChart ref={ref} />;
}

Built-in Locales

All locales are exported from @timelinekit/core and re-exported by the wrapper packages (@timelinekit/react and @timelinekit/angular). English (enLocale) is the default.

import { frLocale } from '@timelinekit/core';

gantt.locale = frLocale;

You can switch locales at runtime — the component re-renders with the new strings immediately.

Locale Structure

A locale implements the TimelineKitLocale interface. It is organized into logical groups:

Custom Locale

Create a fully custom locale by implementing the TimelineKitLocale interface. You can also spread an existing locale and override only specific fields.

import { enLocale, TimelineKitLocale } from '@timelinekit/core';

// Override specific strings
const myLocale: TimelineKitLocale = {
  ...enLocale,
  language: 'en-GB',
  columns: {
    ...enLocale.columns,
    length: 'Duration',
    resources: 'Assignees',
  },
  tooltips: {
    ...enLocale.tooltips,
    addTask: 'New task',
    addLink: 'Create dependency',
  },
};

gantt.locale = myLocale;

Date Formatting

Dates are formatted using the browser's Intl.DateTimeFormat API with the language tag from your locale. This means dates automatically follow the conventions of the selected language — day/month order, month names, separators, and more.

For example, January 15, 2025 renders as:

No additional configuration is needed — just set the correct language tag and the browser handles the rest.

Custom Date Parser

The optional dateParser function lets you define how user-typed date strings in the sheet are interpreted. It receives the raw input and should return a Date object or null if the input is invalid.

import { enLocale, TimelineKitLocale } from '@timelinekit/core';

const locale: TimelineKitLocale = {
  ...enLocale,
  // Parse DD/MM/YYYY format
  dateParser: (value: string) => {
    const parts = value.split('/');
    if (parts.length !== 3) return null;
    const [day, month, year] = parts.map(Number);
    const date = new Date(year, month - 1, day);
    return isNaN(date.getTime()) ? null : date;
  },
};

gantt.locale = locale;

If dateParser is not provided, the component falls back to the browser's default Date parsing.

Full Example

A complete custom locale for Turkish:

import type { TimelineKitLocale } from '@timelinekit/core';

const trLocale: TimelineKitLocale = {
  language: 'tr-TR',

  columns: {
    name: 'Ad',
    length: 'Süre',
    start: 'Başlangıç',
    end: 'Bitiş',
    progress: 'İlerleme',
    resources: 'Kaynaklar',
    work: 'İş',
    cost: 'Maliyet',
  },

  columnTooltips: {
    work: 'Bu göreve ayrılan iş günleri veya saatler.',
    cost: 'Kaynak atandığında otomatik hesaplanan maliyet.',
  },

  tooltips: {
    addTask: 'Görev ekle',
    addTaskPart: 'Görev parçası ekle',
    moveTask: 'Görevi taşı',
    moveTaskPart: 'Görev parçasını taşı',
    resizeTask: 'Görevi boyutlandır',
    resizeTaskPart: 'Görev parçasını boyutlandır',
    moveMilestone: 'Kilometre taşını taşı',
    setProgress: 'İlerlemeyi ayarla',
    addLink: 'Bağlantı ekle',
  },

  labels: {
    start: 'Başlangıç',
    end: 'Bitiş',
    length: 'Süre',
    progress: 'İlerleme',
    from: 'Kaynak',
    to: 'Hedef',
    type: 'Tür',
    lag: 'Gecikme',
  },

  constraints: {
    asap: 'En Kısa Sürede',
    alap: 'En Geç',
    mso: 'Şu Tarihte Başlamalı',
    mfo: 'Şu Tarihte Bitmeli',
    snet: 'Şu Tarihten Önce Başlamamalı',
    snlt: 'Şu Tarihten Sonra Başlamamalı',
    fnet: 'Şu Tarihten Önce Bitmemeli',
    fnlt: 'Şu Tarihten Sonra Bitmemeli',
  },

  linkTypes: {
    finishToStart: 'Bitiş → Başlangıç',
    startToStart: 'Başlangıç → Başlangıç',
    finishToFinish: 'Bitiş → Bitiş',
    startToFinish: 'Başlangıç → Bitiş',
  },

  warnings: {
    behindSchedule: 'Görev planın gerisinde',
    behindScheduleByOneDay: 'bir gün',
    behindScheduleByDays: (days) => `${days} gün`,
    constraintViolation: (label, date) =>
      `Görev '${label} ${date}' kısıtlamasını ihlal ediyor`,
  },

  export: {
    tasksSheetName: 'Görevler',
    linksSheetName: 'Bağlantılar',
    resourcesSheetName: 'Kaynaklar',
    eventsSheetName: 'Etkinlikler',
    calendarsSheetName: 'Takvimler',
  },

  scheduler: {
    resource: 'Kaynak',
    name: 'Ad',
    type: 'Tür',
    addEvent: 'Etkinlik ekle',
    moveEvent: 'Etkinliği taşı',
    resizeEvent: 'Etkinliği boyutlandır',
  },

  calendar: {
    today: 'Bugün',
    month: 'Ay',
    week: 'Hafta',
    day: 'Gün',
    agenda: 'Ajanda',
    allDay: 'tüm gün',
    noEvents: 'Etkinlik yok',
    more: (count) => `+${count} daha`,
    myCalendars: 'Takvimlerim',
    addCalendar: 'Takvim ekle',
  },
};

gantt.locale = trLocale;