React Native Localize Date

This library allows you to localize date and time according to the device locale and additional platform-specific user settings, providing a date localization experience that aligns with users' expectations from native apps.

The output format is platform-dependent and might, for example, even differ between various Android vendors. More information regarding the specifics can be found in the corresponding iOS and Android documentation.

Table of Contents

• Why is this library needed?
• Installation
  • Required additional iOS setup steps
    • Setup with Expo plugin
    • Manual iOS plist steps
• Usage
• API
  • DateStyle
  • new DateFormatter
  • DateFormatter.format
• Running the example app
• Contributing

Why is this library needed?

Localizing date and time based only on a BCP 47 language tag (for example, using react-native-localize) does not yield results as expected on native platforms. This is because the language tag is based on language and region settings, but iOS and Android both provide additional settings to control date and time formatting beyond language and region.

For example, on my iPhone with my personal settings, the language tag that an app will receive is en-US. Using this tag with Intl.DateTimeFormat yields the date format MM/DD/YYYY:

Intl.DateTimeFormat('en-US').format(new Date())
// '11/20/2024'

But with my settings (General > Language & Region > Date Format on iOS 18), as a user, I would expect the date to be formatted as DD/MM/YYYY and thus be 20/11/2024.

This library solves this issue by providing an API for native platform date to localized string formatters.

Installation

Install the library as follows:

npm i react-native-nitro-modules react-native-localize-date
cd ios && pod install

This library was created using Nitro Modules, so it is required to install react-native-nitro-modules as a peer dependency (read more).

The library works with both the new and old architectures. React Native version 0.75.x and above is supported.

Required additional iOS setup steps

You can use the Expo plugin for this additional setup or do it manually in a bare React Native project.

Setup with Expo plugin

After you installed the package, add the following to your app.json plugins array:

{
  "plugins": [
    [
      "react-native-localize-date",
      {
        "defaultLocale": "en",
        "supportedLocales": [
          "en",
          "fr",
          "de"
        ]
      }
    ]
  ]
}

Now run:

npx expo prebuild

Manual iOS plist steps

iOS automatically determines the locale that will be used based on the locales that your app claims to support in the info.plist file. To make use of this library, you need to add the languages you support (CFBundleLocalizations) and a fallback language (CFBundleDevelopmentRegion).

As an example, if your app supports English, French, and German with the fallback language set to English, you should add the following to the info.plist:

<key>CFBundleDevelopmentRegion</key>
<string>en</string>
<key>CFBundleLocalizations</key>
<array>
  <string>en</string>
  <string>fr</string>
  <string>de</string>
</array>

This is all the setup needed for iOS. If you specifically want to know more about how this works on iOS, you can follow these links:

• How iOS Determines the Language For Your App
• CFBundleDevelopmentRegion
• CFBundleLocalizations

Usage

import {
  DateStyle,
  DateFormatter
} from 'react-native-localize-date'

const date = new Date()
const defaultLocale = 'en'
const supportedLocales = ['en', 'fr', 'de']
const shortFormatter = new DateFormatter(defaultLocale, supportedLocales, DateStyle.SHORT, DateStyle.SHORT)

shortFormatter.format(date)
// For example returns: '20/11/2024 16:48'

This repository also contains a full example app using all the different options.

API

DateStyle

Enum representing the different styles for date and time localization. Each value maps to the corresponding style of the current platform.

For more information, refer to the corresponding documentation for iOS and Android.

Value
SHORT
MEDIUM
LONG
FULL

new DateFormatter(defaultLocale: string, supportedLocales: string[], dateStyle: DateStyle, timeStyle: DateStyle)

Creates a DateFormatter with the options specified in the constructor.

defaultLocale is the fallback language that is used when the user does not have any of the supportedLocales in their language settings.

supportedLocales is the list of locales that your app supports. It should not be empty and at least the defaultLocale should be contained in this array.

defaultLocale and supportedLocales are both only used on Android. On iOS, info.plist properties are automatically used. Please refer to the iOS installation steps section.

dateStyle and timeStyle can't both be DateStyle.NONE at the same time. (This will throw an error)

A usage example can be found in the Usage section.

DateFormatter.format(date: Date)

Returns a localized string for the provided date object according to the styles defined when constructing the formatter. A usage example can be found in the Usage section.

Running the example app

There is an example app project located at example/ which you can run as follows:

cd example
npm i
cd ios && pod install && cd ..
npx react-native run-ios

Or run on Android using npx react-native run-android.

Contributing

Since this library uses Nitro Modules, it's best to familiarize yourself with their docs before trying to contribute.

External contributions are always appreciated if something needs to be changed. Please first open an issue to discuss the changes.