@amazon-devices/expo-localization 2.0.1758683737

package/react-native.config.js

@@ -0,0 +1,21 @@
+module.exports = {
+    dependencies: {
+        '@amazon-devices/react-native-kepler': {
+            platforms: {
+                kepler: null,  // do not use platform definition from @react-native-kepler
+            },
+        },
+    },
+    dependency: {
+        platforms: {
+            kepler: {
+                autolink: {
+                    ExpoLocalizationLib: {
+                        provider: 'system',
+                        turbomodules: ['ExpoLocalization'],
+                    },
+                },
+            },
+        },
+    },
+};

package/src/ExpoLocalization.kepler.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * PROPRIETARY/CONFIDENTIAL
+ *
+ * Use is subject to license terms.
+ */
+
+import {KeplerTurboModule, TurboModuleRegistry} from '@amazon-devices/keplerscript-turbomodule-api';
+import {Subscription} from 'expo-modules-core';
+
+import {Calendar, Locale} from './Localization.types';
+
+interface Spec extends KeplerTurboModule {
+    getLocales(): Locale[];
+    getCalendars(): Calendar[];
+}
+
+const nativeModule = TurboModuleRegistry.getEnforcing<Spec>('ExpoLocalization') as Spec;
+const i18nManager = TurboModuleRegistry.getEnforcing('I18nManager') as any;
+
+export function addLocaleListener(listener: (event) => void) {
+    i18nManager.addListener('Locale', listener);
+}
+
+export function addCalendarListener(listener: (event) => void) {
+    i18nManager.addListener('Timezone', listener);
+}
+
+export function removeSubscription(subscription: Subscription) {
+    i18nManager.removeListeners();
+}
+
+const module = {
+    getLocales: nativeModule.getLocales,
+    getCalendars: nativeModule.getCalendars,
+    locale: i18nManager.getAppLocale(),
+};
+
+export default module;

package/src/ExpoLocalization.native.ts

@@ -0,0 +1,18 @@
+import { EventEmitter, Subscription, requireNativeModule } from 'expo-modules-core';
+
+const ExpoLocalizationModule = requireNativeModule('ExpoLocalization');
+const emitter = new EventEmitter(ExpoLocalizationModule);
+
+export function addLocaleListener(listener: (event) => void): Subscription {
+  return emitter.addListener('onLocaleSettingsChanged', listener);
+}
+
+export function addCalendarListener(listener: (event) => void): Subscription {
+  return emitter.addListener('onCalendarSettingsChanged', listener);
+}
+
+export function removeSubscription(subscription: Subscription) {
+  return emitter.removeSubscription(subscription);
+}
+
+export default ExpoLocalizationModule;

package/src/ExpoLocalization.ts

@@ -0,0 +1,203 @@
+/* eslint-env browser */
+import { Platform, Subscription } from 'expo-modules-core';
+import * as rtlDetect from 'rtl-detect';
+
+import { Localization, Calendar, Locale, CalendarIdentifier } from './Localization.types';
+
+const getNavigatorLocales = () => {
+  return Platform.isDOMAvailable ? navigator.languages || [navigator.language] : [];
+};
+
+type ExtendedLocale = Intl.Locale &
+  // typescript definitions for navigator language don't include some modern Intl properties
+  Partial<{
+    textInfo: { direction: 'ltr' | 'rtl' };
+    timeZones: string[];
+    weekInfo: { firstDay: number };
+    hourCycles: string[];
+    timeZone: string;
+    calendars: string[];
+  }>;
+
+const WEB_LANGUAGE_CHANGE_EVENT = 'languagechange';
+// https://wisevoter.com/country-rankings/countries-that-use-fahrenheit/
+const USES_FAHRENHEIT = [
+  'AG',
+  'BZ',
+  'VG',
+  'FM',
+  'MH',
+  'MS',
+  'KN',
+  'BS',
+  'CY',
+  'TC',
+  'US',
+  'LR',
+  'PW',
+  'KY',
+];
+
+export function addLocaleListener(listener: (event) => void): Subscription {
+  addEventListener(WEB_LANGUAGE_CHANGE_EVENT, listener);
+  return {
+    remove: () => removeEventListener(WEB_LANGUAGE_CHANGE_EVENT, listener),
+  };
+}
+
+export function addCalendarListener(listener: (event) => void): Subscription {
+  addEventListener(WEB_LANGUAGE_CHANGE_EVENT, listener);
+  return {
+    remove: () => removeEventListener(WEB_LANGUAGE_CHANGE_EVENT, listener),
+  };
+}
+
+export function removeSubscription(subscription: Subscription) {
+  subscription.remove();
+}
+
+export default {
+  get currency(): string | null {
+    // TODO: Add support
+    return null;
+  },
+  get decimalSeparator(): string {
+    return (1.1).toLocaleString().substring(1, 2);
+  },
+  get digitGroupingSeparator(): string {
+    const value = (1000).toLocaleString();
+    return value.length === 5 ? value.substring(1, 2) : '';
+  },
+  get isRTL(): boolean {
+    return rtlDetect.isRtlLang(this.locale) ?? false;
+  },
+  get isMetric(): boolean {
+    const { region } = this;
+    switch (region) {
+      case 'US': // USA
+      case 'LR': // Liberia
+      case 'MM': // Myanmar
+        return false;
+    }
+    return true;
+  },
+  get locale(): string {
+    if (!Platform.isDOMAvailable) {
+      return '';
+    }
+    const locale =
+      navigator.language ||
+      navigator['systemLanguage'] ||
+      navigator['browserLanguage'] ||
+      navigator['userLanguage'] ||
+      this.locales[0];
+    return locale;
+  },
+  get locales(): string[] {
+    if (!Platform.isDOMAvailable) {
+      return [];
+    }
+    const { languages = [] } = navigator;
+    return Array.from(languages);
+  },
+  get timezone(): string {
+    const defaultTimeZone = 'Etc/UTC';
+    if (typeof Intl === 'undefined') {
+      return defaultTimeZone;
+    }
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || defaultTimeZone;
+  },
+  get isoCurrencyCodes(): string[] {
+    // TODO(Bacon): Add this - very low priority
+    return [];
+  },
+  get region(): string | null {
+    // There is no way to obtain the current region, as is possible on native.
+    // Instead, use the country-code from the locale when possible (e.g. "en-US").
+    const { locale } = this;
+    const [, ...suffixes] = typeof locale === 'string' ? locale.split('-') : [];
+    for (const suffix of suffixes) {
+      if (suffix.length === 2) {
+        return suffix.toUpperCase();
+      }
+    }
+    return null;
+  },
+
+  getLocales(): Locale[] {
+    const locales = getNavigatorLocales();
+    return locales?.map((languageTag) => {
+      // TextInfo is an experimental API that is not available in all browsers.
+      // We might want to consider using a locale lookup table instead.
+      const locale =
+        typeof Intl !== 'undefined'
+          ? (new Intl.Locale(languageTag) as unknown as ExtendedLocale)
+          : { region: null, textInfo: null, language: null };
+      const { region, textInfo, language } = locale;
+
+      // Properties added only for compatibility with native, use `toLocaleString` instead.
+      const digitGroupingSeparator =
+        Array.from((10000).toLocaleString(languageTag)).filter((c) => c > '9' || c < '0')[0] ||
+        null; // using 1e5 instead of 1e4 since for some locales (like pl-PL) 1e4 does not use digit grouping
+      const decimalSeparator = (1.1).toLocaleString(languageTag).substring(1, 2);
+      const temperatureUnit = region ? regionToTemperatureUnit(region) : null;
+
+      return {
+        languageTag,
+        languageCode: language || languageTag.split('-')[0] || 'en',
+        textDirection: (textInfo?.direction as 'ltr' | 'rtl') || null,
+        digitGroupingSeparator,
+        decimalSeparator,
+        measurementSystem: null,
+        currencyCode: null,
+        currencySymbol: null,
+        regionCode: region || null,
+        temperatureUnit,
+      };
+    });
+  },
+  getCalendars(): Calendar[] {
+    const locale = ((typeof Intl !== 'undefined'
+      ? Intl.DateTimeFormat().resolvedOptions()
+      : null) ?? null) as unknown as null | ExtendedLocale;
+    return [
+      {
+        calendar: ((locale?.calendar || locale?.calendars?.[0]) as CalendarIdentifier) || null,
+        timeZone: locale?.timeZone || locale?.timeZones?.[0] || null,
+        uses24hourClock: (locale?.hourCycle || locale?.hourCycles?.[0])?.startsWith('h2') ?? null, //https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle
+        firstWeekday: locale?.weekInfo?.firstDay || null,
+      },
+    ];
+  },
+
+  async getLocalizationAsync(): Promise<Omit<Localization, 'getCalendars' | 'getLocales'>> {
+    const {
+      currency,
+      decimalSeparator,
+      digitGroupingSeparator,
+      isoCurrencyCodes,
+      isMetric,
+      isRTL,
+      locale,
+      locales,
+      region,
+      timezone,
+    } = this;
+    return {
+      currency,
+      decimalSeparator,
+      digitGroupingSeparator,
+      isoCurrencyCodes,
+      isMetric,
+      isRTL,
+      locale,
+      locales,
+      region,
+      timezone,
+    };
+  },
+};
+
+function regionToTemperatureUnit(region: string) {
+  return USES_FAHRENHEIT.includes(region) ? 'fahrenheit' : 'celsius';
+}

package/src/Localization.ts

@@ -0,0 +1,217 @@
+import { useEffect, useReducer, useMemo } from 'react';
+
+import ExpoLocalization, {
+  addCalendarListener,
+  addLocaleListener,
+  removeSubscription,
+} from './ExpoLocalization';
+import { Localization } from './Localization.types';
+export * from './Localization.types';
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * Three-character ISO 4217 currency code. Returns `null` on web.
+ *
+ * @example `'USD'`, `'EUR'`, `'CNY'`, `null`
+ */
+export const currency = ExpoLocalization.currency;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * Decimal separator used for formatting numbers.
+ *
+ * @example `','`, `'.'`
+ */
+export const decimalSeparator = ExpoLocalization.decimalSeparator;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * Digit grouping separator used when formatting numbers larger than 1000.
+ *
+ * @example `'.'`, `''`, `','`
+ */
+export const digitGroupingSeparator = ExpoLocalization.digitGroupingSeparator;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * A list of all the supported language ISO codes.
+ */
+export const isoCurrencyCodes = ExpoLocalization.isoCurrencyCodes;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * Boolean value that indicates whether the system uses the metric system.
+ * On Android and web, this is inferred from the current region.
+ */
+export const isMetric = ExpoLocalization.isMetric;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * Returns if the system's language is written from Right-to-Left.
+ * This can be used to build features like [bidirectional icons](https://material.io/design/usability/bidirectionality.html).
+ *
+ * Returns `false` in Server Side Rendering (SSR) environments.
+ */
+export const isRTL = ExpoLocalization.isRTL;
+
+// @needsAudit
+/**
+ * Consider using Localization.getLocales() for a list of user preferred locales instead.
+ * An [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag),
+ * consisting of a two-character language code and optional script, region and variant codes.
+ *
+ * @example `'en'`, `'en-US'`, `'zh-Hans'`, `'zh-Hans-CN'`, `'en-emodeng'`
+ */
+export const locale = ExpoLocalization.locale;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * List of all the native languages provided by the user settings.
+ * These are returned in the order the user defines in their device settings.
+ *
+ * @example `['en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng']`
+ */
+export const locales = ExpoLocalization.locales;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getCalendars() instead.
+ * The current time zone in display format.
+ * On Web time zone is calculated with Intl.DateTimeFormat().resolvedOptions().timeZone. For a
+ * better estimation you could use the moment-timezone package but it will add significant bloat to
+ * your website's bundle size.
+ *
+ * @example `'America/Los_Angeles'`
+ */
+export const timezone = ExpoLocalization.timezone;
+
+// @needsAudit
+/**
+ * @deprecated Use Localization.getLocales() instead.
+ * The region code for your device that comes from the Region setting under Language & Region on iOS.
+ * This value is always available on iOS, but might return `null` on Android or web.
+ *
+ * @example `'US'`, `'NZ'`, `null`
+ */
+export const region = ExpoLocalization.region;
+
+/**
+ * List of user's locales, returned as an array of objects of type `Locale`.
+ * Guaranteed to contain at least 1 element.
+ * These are returned in the order the user defines in their device settings.
+ * On the web currency and measurements systems are not provided, instead returned as null.
+ * If needed, you can infer them from the current region using a lookup table.
+ * @example `[{
+    "languageTag": "pl-PL",
+    "languageCode": "pl",
+    "textDirection": "ltr",
+    "digitGroupingSeparator": " ",
+    "decimalSeparator": ",",
+    "measurementSystem": "metric",
+    "currencyCode": "PLN",
+    "currencySymbol": "zł",
+    "regionCode": "PL",
+    "temperatureUnit": "celsius"
+  }]`
+ */
+export const getLocales = ExpoLocalization.getLocales;
+
+/**
+ * List of user's preferred calendars, returned as an array of objects of type `Calendar`.
+ * Guaranteed to contain at least 1 element.
+ * For now always returns a single element, but it's likely to return a user preference list on some platforms in the future.
+ * @example `[
+    {
+      "calendar": "gregory",
+      "timeZone": "Europe/Warsaw",
+      "uses24hourClock": true,
+      "firstWeekday": 1
+    }
+  ]`
+ */
+export const getCalendars = ExpoLocalization.getCalendars;
+
+/**
+ * A hook providing a list of user's locales, returned as an array of objects of type `Locale`.
+ * Guaranteed to contain at least 1 element.
+ * These are returned in the order the user defines in their device settings.
+ * On the web currency and measurements systems are not provided, instead returned as null.
+ * If needed, you can infer them from the current region using a lookup table.
+ * If the OS settings change, the hook will rerender with a new list of locales.
+ * @example `[{
+    "languageTag": "pl-PL",
+    "languageCode": "pl",
+    "textDirection": "ltr",
+    "digitGroupingSeparator": " ",
+    "decimalSeparator": ",",
+    "measurementSystem": "metric",
+    "currencyCode": "PLN",
+    "currencySymbol": "zł",
+    "regionCode": "PL",
+    "temperatureUnit": "celsius"
+  }]`
+ */
+export function useLocales() {
+  const [key, invalidate] = useReducer((k) => k + 1, 0);
+  const locales = useMemo(() => getLocales(), [key]);
+  useEffect(() => {
+    const subscription = addLocaleListener(invalidate);
+    return () => {
+      removeSubscription(subscription);
+    };
+  }, []);
+  return locales;
+}
+
+/**
+ * A hook providing a list of user's preferred calendars, returned as an array of objects of type `Calendar`.
+ * Guaranteed to contain at least 1 element.
+ * For now always returns a single element, but it's likely to return a user preference list on some platforms in the future.
+ * If the OS settings change, the hook will rerender with a new list of calendars.
+ * @example `[
+    {
+      "calendar": "gregory",
+      "timeZone": "Europe/Warsaw",
+      "uses24hourClock": true,
+      "firstWeekday": 1
+    }
+  ]`
+ */
+export function useCalendars() {
+  const [key, invalidate] = useReducer((k) => k + 1, 0);
+  const calendars = useMemo(() => getCalendars(), [key]);
+  useEffect(() => {
+    const subscription = addCalendarListener(invalidate);
+    return () => {
+      removeSubscription(subscription);
+    };
+  }, []);
+  return calendars;
+}
+
+// @needsAudit
+/**
+ * Get the latest native values from the device. Locale can be changed on some Android devices
+ * without resetting the app.
+ * > On iOS, changing the locale will cause the device to reset meaning the constants will always be
+ * correct.
+ *
+ * @example
+ * ```ts
+ * // When the app returns from the background on Android...
+ *
+ * const { locale } = await Localization.getLocalizationAsync();
+ * ```
+ * @deprecated
+ * Use Localization.getLocales() or Localization.getCalendars() instead.
+ */
+export async function getLocalizationAsync(): Promise<Localization> {
+  return await ExpoLocalization.getLocalizationAsync();
+}