timepicker-ui
4.7.0GitHub
timepicker-ui
GitHub4.7.0
Advanced / Localization

Localization

Customize labels and formats for international audiences

Examples: LocalizationCustom Labels

Custom Labels

#

Timepicker-UI allows you to customize all text labels to support any language:

Default Labels

The labels group with its English defaults, without the deprecated keys. Keys you leave out keep these values. clock, period, timeFields, range, switchToKeyboard, switchToClock and the keys that start with announce are read by screen readers only.

index.ts
// Default English labels
{
  labels: {
    am: 'AM',
    pm: 'PM',
    ok: 'OK',
    cancel: 'Cancel',
    clear: 'Clear',
    clockTitle: 'Select time',
    keyboardTitle: 'Enter Time',
    hour: 'Hour',
    minute: 'Minute',
    second: 'Second',
    valueText: '{value} of {count}',
    clock: 'Clock',
    period: 'Period',
    timeFields: 'Time',
    range: 'Range selection',
    rangeFrom: 'From',
    rangeTo: 'To',
    timezone: 'Timezone',
    switchToKeyboard: 'Switch to keyboard input',
    switchToClock: 'Switch to clock',
    announceAmSelected: 'AM selected',
    announcePmSelected: 'PM selected',
    announceCleared: 'Time cleared',
    invalidTimeFormat: 'Invalid time format'
  }
}

hour, minute and second each set the field caption, the field's accessible name, the dial name and the prefix of the screen-reader announcement. The minute announcement says Minute by default, and said Minutes before 4.7.0. second is used only with clock.showSeconds: true. range, rangeFrom and rangeTo are used by the range plugin, and timezone by the timezone plugin. Keys renamed in 4.5.0 are listed on the Options page.

valueText is the screen reader value of the hour, minute and second fields and of the dial. {value} is the number without a leading zero and {count} the number of values on that face. With the field name it reads "Hour, 7 of 12". Translate the words around the placeholders, for example '{value} z {count}', or use '{value}' for the bare number. New in 4.7.0.

labels.am and labels.pm change only the text on screen and what screen readers announce. The input value and getValue().type always use AM / PM.

Spanish Localization

index.ts
const picker = new TimepickerUI(input, {
  labels: {
    ok: 'Aceptar',
    cancel: 'Cancelar',
    am: 'AM',
    pm: 'PM'
  }
});


picker.create();

French Localization

index.ts
const picker = new TimepickerUI(input, {
  labels: {
    ok: 'Valider',
    cancel: 'Annuler',
    am: 'AM',
    pm: 'PM'
  }
});


picker.create();

German Localization

index.ts
const picker = new TimepickerUI(input, {
  labels: {
    ok: 'OK',
    cancel: 'Abbrechen',
    am: 'AM',
    pm: 'PM'
  }
});


picker.create();

Language Configuration Object

#

Create reusable language configuration objects for consistency:

Language Config Files

index.ts
// locales/es.ts
export const esLocale = {
  labels: {
    ok: 'Aceptar',
    cancel: 'Cancelar',
    am: 'AM',
    pm: 'PM'
  }
};


// locales/fr.ts
export const frLocale = {
  labels: {
    ok: 'Valider',
    cancel: 'Annuler',
    am: 'AM',
    pm: 'PM'
  }
};


// locales/de.ts
export const deLocale = {
  labels: {
    ok: 'OK',
    cancel: 'Abbrechen',
    am: 'AM',
    pm: 'PM'
  }
};


// locales/ja.ts
export const jaLocale = {
  labels: {
    ok: '確認',
    cancel: 'キャンセル',
    am: '午前',
    pm: '午後'
  }
};


// locales/zh.ts
export const zhLocale = {
  labels: {
    ok: '确定',
    cancel: '取消',
    am: '上午',
    pm: '下午'
  }
};

Using Language Configs

index.ts
import { TimepickerUI } from 'timepicker-ui';
import { esLocale } from './locales/es';


const picker = new TimepickerUI(input, {
  ...esLocale,
  clock: { type: '24h' }
});


picker.create();

Dynamic Language Switching

index.ts
import { esLocale, frLocale, deLocale } from './locales';


const locales = {
  es: esLocale,
  fr: frLocale,
  de: deLocale
};


function createLocalizedPicker(language: string) {
  const locale = locales[language] || esLocale;


  const picker = new TimepickerUI(input, {
    ...locale,
    clock: { type: '24h' }
  });


  return picker;
}


// Usage
let picker = createLocalizedPicker('es');
picker.create();


// Switch language
picker.destroy();
picker = createLocalizedPicker('fr');
picker.create();

Time Format Localization

#

Different regions use different time formats. Configure the clock type based on locale:

12-hour Format (US, UK, Canada)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '12h' },
  labels: {
    ok: 'OK',
    cancel: 'Cancel',
    am: 'AM',
    pm: 'PM'
  }
});

24-hour Format (Europe, Asia, Most of World)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: 'OK',
    cancel: 'Annuler'
  }
  // No am/pm labels needed for 24h format
});

Auto-detect User Locale

clock.type: 'auto' picks 12h or 24h from the browser locale when the picker is created and each time its options are set. New in 4.5.0.

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: 'auto' }
});


picker.create();

Complete Locale Examples

#

Ready-to-use configurations for common languages:

Japanese (日本語)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: '確認',
    cancel: 'キャンセル'
  }
});

Chinese Simplified (简体中文)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: '确定',
    cancel: '取消'
  }
});

Arabic (العربية)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '12h' },
  labels: {
    ok: 'موافق',
    cancel: 'إلغاء',
    am: 'ص',
    pm: 'م'
  }
});

Russian (Русский)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: 'ОК',
    cancel: 'Отмена'
  }
});

Portuguese (Português)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: 'Confirmar',
    cancel: 'Cancelar'
  }
});

Italian (Italiano)

index.ts
const picker = new TimepickerUI(input, {
  clock: { type: '24h' },
  labels: {
    ok: 'OK',
    cancel: 'Annulla'
  }
});

React i18n Integration

#

Integrate with popular i18n libraries:

react-i18next

index.ts
import { useTranslation } from 'react-i18next';
import { useEffect, useRef } from 'react';
import { TimepickerUI } from 'timepicker-ui';


function LocalizedTimePicker() {
  const { t, i18n } = useTranslation();
  const inputRef = useRef<HTMLInputElement>(null);
  const pickerRef = useRef<TimepickerUI | null>(null);


  useEffect(() => {
    if (inputRef.current) {
      pickerRef.current = new TimepickerUI(inputRef.current, {
        clock: {
          type: i18n.language.includes('en') ? '12h' : '24h'
        },
        labels: {
          ok: t('timepicker.ok'),
          cancel: t('timepicker.cancel'),
          am: t('timepicker.am'),
          pm: t('timepicker.pm')
        }
      });


      pickerRef.current.create();
    }


    return () => {
      pickerRef.current?.destroy();
    };
  }, [t, i18n.language]);


  return <input ref={inputRef} type="text" />;
}

i18n Translation File

index.json
// locales/en/translation.json
{
  "timepicker": {
    "ok": "OK",
    "cancel": "Cancel",
    "am": "AM",
    "pm": "PM"
  }
}


// locales/es/translation.json
{
  "timepicker": {
    "ok": "Aceptar",
    "cancel": "Cancelar",
    "am": "AM",
    "pm": "PM"
  }
}


// locales/fr/translation.json
{
  "timepicker": {
    "ok": "Valider",
    "cancel": "Annuler",
    "am": "AM",
    "pm": "PM"
  }
}

Right-to-Left (RTL) Support

#

The picker has no built-in RTL layout. The modal is appended to body unless ui.appendTo is set, so a dir attribute on a wrapper around the input does not reach it. Put dir="rtl" on <html>, or append the modal to your RTL container:

index.html
<div id="rtl-root" dir="rtl">
  <input id="timepicker" type="text" />
</div>
index.ts
const picker = new TimepickerUI('#timepicker', {
  clock: { type: '12h' },
  ui: { appendTo: '#rtl-root' },
  labels: {
    ok: 'موافق',
    cancel: 'إلغاء',
    am: 'ص',
    pm: 'م'
  }
});


picker.create();

direction: rtl also reverses flex rows, including the hour and minute fields. To keep them in HH:MM order, reset the direction on the field group:

index.css
[dir="rtl"] .tp-ui-wrapper-time {
  direction: ltr;
}
Contributing Translations
If you'd like to contribute translations for additional languages to the official documentation or create a locale pack, please open a pull request on GitHub. Community translations help make Timepicker-UI accessible to users worldwide.
View on GitHub
Esc