# General Translation Platform: formatDateTime URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/formatting/format-date-time.mdx Docs index: https://generaltranslation.com/llms.txt Description: Format dates and times by locale. API reference for formatDateTime. Formats a date and time according to locale-specific conventions on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation uses the built-in `Intl.DateTimeFormat` API to handle date formats, time formats, calendars, and time zones automatically for the target locale. ## Overview [#overview] Call `formatDateTime` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with a `Date` and an optional options object. It returns the formatted date and time as a string. ```typescript const gt = new GT({ targetLocale: 'de-DE' }); const formatted = gt.formatDateTime(new Date(), { dateStyle: 'medium', timeStyle: 'short', }); // "25.09.2025, 18:06" (German date/time formatting) ``` Signature: ```typescript formatDateTime( date: Date, options?: { locales?: string | string[] } & Intl.DateTimeFormatOptions ): string ``` *Note: `formatDateTime` runs locally using `Intl.DateTimeFormat` and does not require an API key. It uses the instance's target locale by default, then falls back to the source locale and `en`; pass `locales` to override. For formatting without a `GT` instance, see the standalone [`formatDateTime`](/docs/platform/core/reference/utility-functions/formatting/format-date-time).* ## How it works [#how-it-works] * **Locale resolution.** By default, the method formats for the instance's target locale, falling back to the source locale and then `en`. Pass `locales` in the options to override it for a single call. * **Intl-backed.** Formatting is delegated to the browser-native [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat), so all standard `Intl.DateTimeFormatOptions` are supported. * **Time zones.** Time zones are handled correctly when a `timeZone` is specified; otherwise, the runtime's local time zone is used. ## Parameters [#parameters] | Parameter | Description | Type | Optional | Default | | --------------------- | ------------------------------------------------------------------------------------------- | -------- | -------- | ------- | | [`date`](#date) | The date object to format. | `Date` | No | — | | [`options`](#options) | Formatting configuration, extending `Intl.DateTimeFormatOptions` with a `locales` override. | `object` | Yes | — | ### `date` [#date] **Type** `Date` · **Required** The `Date` object to format. ### `options` [#options] **Type** `{ locales?: string | string[] } & Intl.DateTimeFormatOptions` · **Optional** Formatting configuration. The table lists common options exposed by the published Core types and their effective Core defaults. (See the [`Intl.DateTimeFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) for additional standard and runtime-specific details). | Name | Description | Type | Optional | Default | | ------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ | | `locales` | Override locales for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `en` | | `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` | | `dateStyle` | Overall date formatting style. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | | `timeStyle` | Overall time formatting style. | `'full' \| 'long' \| 'medium' \| 'short'` | Yes | — | | `weekday` | Weekday representation. | `'long' \| 'short' \| 'narrow'` | Yes | — | | `era` | Era representation. | `'long' \| 'short' \| 'narrow'` | Yes | — | | `year` | Year representation. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | | `month` | Month representation. | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | Yes | `'numeric'` when no styles or components are set | | `day` | Day representation. | `'numeric' \| '2-digit'` | Yes | `'numeric'` when no styles or components are set | | `dayPeriod` | Day period formatting (morning, afternoon, etc.). | `'narrow' \| 'short' \| 'long'` | Yes | — | | `hour` | Hour representation. | `'numeric' \| '2-digit'` | Yes | — | | `minute` | Minute representation. | `'numeric' \| '2-digit'` | Yes | — | | `second` | Second representation. | `'numeric' \| '2-digit'` | Yes | — | | `fractionalSecondDigits` | Number of fractional second digits. | `1 \| 2 \| 3` | Yes | — | | `timeZoneName` | Time zone name format. | `'long' \| 'short' \| 'longOffset' \| 'shortOffset' \| 'longGeneric' \| 'shortGeneric'` | Yes | — | | `timeZone` | IANA time zone name or supported UTC offset identifier. | `string` | Yes | runtime time zone | | `hour12` | Whether to use 12-hour time format. | `boolean` | Yes | locale-dependent | | `hourCycle` | Hour cycle preference. | `'h11' \| 'h12' \| 'h23' \| 'h24'` | Yes | locale-dependent | | `calendar` | Calendar system to use. | `string` | Yes | `'gregory'` | | `numberingSystem` | Numbering system for digits. | `string` | Yes | `'latn'` | | `formatMatcher` | Format matching algorithm. | `'basic' \| 'best fit'` | Yes | `'best fit'` | `dateStyle` and `timeStyle` can be combined with each other, but not with individual date-time component options such as `year`, `month`, or `hour`. `hour12` overrides `hourCycle`, and `dayPeriod` only affects 12-hour cycles. Core sets `calendar: 'gregory'` and `numberingSystem: 'latn'`; upstream `Intl.DateTimeFormat` otherwise chooses both from the locale. ## Returns [#returns] **Type** `string` The formatted date and time, following the target locale’s conventions. ## Examples [#examples] *Note: examples without an explicit `timeZone` render in the runtime's local time zone; the time-of-day outputs below assume `America/Los_Angeles` (UTC−7 on this date).* ```typescript import { GT } from 'generaltranslation'; const gt = new GT({ targetLocale: 'en-US' }); const date = new Date('2024-03-14T14:30:45Z'); // Basic date formatting (uses default options) console.log(gt.formatDateTime(date)); // Output: "3/14/2024" // German locale formatting console.log(gt.formatDateTime(date, { locales: 'de-DE' })); // Output: "14.3.2024" // Japanese locale formatting console.log(gt.formatDateTime(date, { locales: 'ja-JP' })); // Output: "2024/3/14" ``` ```typescript // Date and time styles const date = new Date('2024-03-14T14:30:45Z'); // Full date style console.log(gt.formatDateTime(date, { dateStyle: 'full' })); // Output: "Thursday, March 14, 2024" // Long date with short time console.log(gt.formatDateTime(date, { dateStyle: 'long', timeStyle: 'short', })); // Output: "March 14, 2024 at 7:30 AM" // Custom date components console.log(gt.formatDateTime(date, { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric', })); // Output: "Thursday, March 14, 2024" ``` ```typescript // Time zone and hour format const date = new Date('2024-03-14T14:30:45Z'); // Force 12-hour format console.log(gt.formatDateTime(date, { hour: 'numeric', minute: '2-digit', hour12: true, })); // Output: "7:30 AM" // Force 24-hour format console.log(gt.formatDateTime(date, { hour: 'numeric', minute: '2-digit', hour12: false, })); // Output: "07:30" // Specific time zone console.log(gt.formatDateTime(date, { timeZone: 'America/New_York', dateStyle: 'medium', timeStyle: 'short', })); // Output: "Mar 14, 2024, 10:30 AM" ``` ## Notes [#notes] * Date formatting automatically follows locale-specific conventions. * The method uses browser-native `Intl.DateTimeFormat` for performance and accuracy. * Time zones are handled correctly when specified. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.