This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

Expo 本地化

一个为原生用户本地化信息提供接口的库。

Android

iOS

tvOS

Web

Included in Expo Go

GitHub

npm

更新日志

expo-localization 允许您将应用本地化，为特定地区、语言或文化定制使用体验。它还提供对原生设备上区域设置数据的访问。将 lingui-js、react-i18next、react-intl、i18n-js 或 react-native-intlayer 等本地化库与 expo-localization 结合使用，可以帮助您为用户打造非常易于访问的体验。

安装

Terminal

- npx expo install expo-localization

If you are installing this in an existing React Native app, make sure to install expo in your project.

app config 中的配置

如果你在项目中使用 config plugins（持续原生生成 (CNG)），你可以使用 expo-localization 内置的 config plugin 进行配置。该插件允许你配置各种无法在运行时设置的属性，并且这些属性需要重新构建新的应用二进制文件后才会生效。如果你的应用不使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-localization",
        {
          "supportsRTL": true,
          "forcesRTL": false,
          "supportedLocales": ["en", "ja"]
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`supportsRTL`	`true`	应用是否允许 RTL 布局。启用后，应用会根据 RTL 设备语言使用 RTL 布局，遵循 React Native 的 `I18nManager`。
`forcesRTL`	`false`	是否无论设备语言为何都强制使用 RTL 布局。适用于测试，或仅针对 RTL 区域设置本地化的应用。
`supportedLocales`	`undefined`	应用支持的区域设置，用于在系统设置中启用按应用选择语言的功能。可以提供一个供两个平台共用的数组，也可以分别提供平台专属的 `ios` 和 `android` 数组。

使用

有关使用 expo-localization 以及为从右到左语言添加支持的更多信息，请参阅本地化指南。

API

import { getLocales, getCalendars } from 'expo-localization';

行为

你可以使用同步的 getLocales() 和 getCalendars() 方法来获取用户设备的区域设置。在 iOS 上，只要应用正在运行，结果将保持不变。

在 Android 上，用户可以在“设置”中更改区域设置偏好，而无需重启应用。为了保持本地化内容的最新状态，你可以在应用每次返回前台时重新运行 getLocales() 和 getCalendars() 方法。使用 AppState 来检测这一点。

Hooks

`useCalendars()`

Android

iOS

tvOS

Web

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.

Returns:

[Calendar, ...Calendar[]]

Example

[{
  "calendar": "gregory",
  "timeZone": "Europe/Warsaw",
  "uses24hourClock": true,
  "firstWeekday": 1
}]

`useLocales()`

Android

iOS

tvOS

Web

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.

Returns:

[Locale, ...Locale[]]

Example

[{
  "languageTag": "pl-PL",
  "languageCode": "pl",
  "textDirection": "ltr",
  "digitGroupingSeparator": " ",
  "decimalSeparator": ",",
  "measurementSystem": "metric",
  "currencyCode": "PLN",
  "currencySymbol": "zł",
  "regionCode": "PL",
  "temperatureUnit": "celsius"
}]

Methods

`Localization.getCalendars()`

Android

iOS

tvOS

Web

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.

Returns:

[Calendar, ...Calendar[]]

Example

[{
  "calendar": "gregory",
  "timeZone": "Europe/Warsaw",
  "uses24hourClock": true,
  "firstWeekday": 1
}]

`Localization.getLocales()`

Android

iOS

tvOS

Web

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.

Returns:

[Locale, ...Locale[]]

Example

[{
  "languageTag": "pl-PL",
  "languageCode": "pl",
  "textDirection": "ltr",
  "digitGroupingSeparator": " ",
  "decimalSeparator": ",",
  "measurementSystem": "metric",
  "currencyCode": "PLN",
  "currencySymbol": "zł",
  "regionCode": "PL",
  "temperatureUnit": "celsius"
}]

Types

`Calendar`

Android

iOS

tvOS

Web

Property	Type	Description
calendar	`CalendarIdentifier \| null`	The calendar identifier, one of Unicode calendar types. On Android is limited to one of device's available calendar types. On iOS uses calendar identifiers, but maps them to the corresponding Unicode types, will also never contain `'dangi'` or `'islamic-rgsa'` due to it not being implemented on iOS.
firstWeekday	`Weekday \| null`	The first day of the week. For most calendars Sunday is numbered `1`, with Saturday being number `7`. Can be null on some browsers that don't support the weekInfo property in Intl API. Example `1`, `7`.
timeZone	`string \| null`	Time zone for the calendar. Can be `null` on Web. Example `'America/Los_Angeles'`, `'Europe/Warsaw'`, `'GMT+1'`.
uses24hourClock	`boolean \| null`	True when current device settings use 24-hour time format. Can be null on some browsers that don't support the hourCycle property in Intl API.

`Locale`

Android

iOS

tvOS

Web

Property	Type	Description
currencyCode	`string \| null`	Currency code for the locale. On iOS, it's the currency code from the `Region` setting under Language & Region, not for the current locale. On Android, it's the currency specific to the locale in the list, as there are no separate settings for selecting a region. Is `null` on Web, use a table lookup based on region instead. Example `'USD'`, `'EUR'`, `'PLN'`.
currencySymbol	`string \| null`	Currency symbol for the currency specified by `currencyCode`. Example `'$'`, `'€'`, `'zł'`.
decimalSeparator	`string \| null`	Decimal separator used for formatting numbers with fractional parts. Example `'.'`, `','`.
digitGroupingSeparator	`string \| null`	Digit grouping separator used for formatting large numbers. Example `'.'`, `','`.
languageCode	`string \| null`	An IETF BCP 47 language tag without the region code. Example `'en'`, `'es'`, `'pl'`.
languageCurrencyCode	`string \| null`	Currency code for the locale. On iOS, it's the currency code for the current locale in the list, not the device region. On Android, it's equal to `currencyCode`. Is `null` on Web. Prefer using `currencyCode` for any internalization purposes. Example `'USD'`, `'EUR'`, `'PLN'`.
languageCurrencySymbol	`string \| null`	Currency symbol for the currency specified by `languageCurrencyCode`. Prefer using `currencySymbol` for any internalization purposes. Example `'$'`, `'€'`, `'zł'`.
languageRegionCode	`string \| null`	The region code for the preferred language. When the language is not region-specific, it returns the same value as `regionCode`. When the language is region-specific, it returns the region code for the language (`en-CA` -> `CA`). Prefer using `regionCode` for any internalization purposes. Example `'US'`.
languageScriptCode	`string \| null`	An ISO 15924 4-letter script code. On Android and Web, it may be `null` if none is defined. Example `'Latn'`, `'Hans'`, `'Hebr'`.
languageTag	`string`	An IETF BCP 47 language tag with a region code. Example `'en-US'`, `'es-419'`, `'pl-PL'`.
measurementSystem	`'metric' \| 'us' \| 'uk' \| null`	The measurement system used in the locale. Is `null` on Web, as user chosen measurement system is not exposed on the web and using locale to determine measurement systems is unreliable. Ask for user preferences if possible.
regionCode	`string \| null`	The region code for your device that comes from the Region setting under Language & Region on iOS, Region settings on Android and is parsed from locale on Web (can be `null` on Web). Example `'US'`.
temperatureUnit	`'celsius' \| 'fahrenheit' \| null`	The temperature unit used in the locale. Returns `null` if the region code is unknown.
textDirection	`'ltr' \| 'rtl'`	Text direction for the locale. One of: `'ltr'`, `'rtl'`.

Enums

`CalendarIdentifier`

Android

iOS

tvOS

Web

The calendar identifier, one of Unicode calendar types. Gregorian calendar is aliased and can be referred to as both CalendarIdentifier.GREGORIAN and CalendarIdentifier.GREGORY.

`BUDDHIST`

CalendarIdentifier.BUDDHIST ＝ "buddhist"

Thai Buddhist calendar

`CHINESE`

CalendarIdentifier.CHINESE ＝ "chinese"

Traditional Chinese calendar

`COPTIC`

CalendarIdentifier.COPTIC ＝ "coptic"

Coptic calendar

`DANGI`

CalendarIdentifier.DANGI ＝ "dangi"

Traditional Korean calendar

`ETHIOAA`

CalendarIdentifier.ETHIOAA ＝ "ethioaa"

Ethiopic calendar, Amete Alem (epoch approx. 5493 B.C.E)

`ETHIOPIC`

CalendarIdentifier.ETHIOPIC ＝ "ethiopic"

Ethiopic calendar, Amete Mihret (epoch approx, 8 C.E.)

`GREGORIAN`

CalendarIdentifier.GREGORIAN ＝ "gregory"

Gregorian calendar (alias)

`GREGORY`

CalendarIdentifier.GREGORY ＝ "gregory"

Gregorian calendar

`HEBREW`

CalendarIdentifier.HEBREW ＝ "hebrew"

Traditional Hebrew calendar

`INDIAN`

CalendarIdentifier.INDIAN ＝ "indian"

Indian calendar

`ISLAMIC`

CalendarIdentifier.ISLAMIC ＝ "islamic"

Islamic calendar

`ISLAMIC_CIVIL`

CalendarIdentifier.ISLAMIC_CIVIL ＝ "islamic-civil"

Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - civil epoch)

`ISLAMIC_RGSA`

CalendarIdentifier.ISLAMIC_RGSA ＝ "islamic-rgsa"

Islamic calendar, Saudi Arabia sighting

`ISLAMIC_TBLA`

CalendarIdentifier.ISLAMIC_TBLA ＝ "islamic-tbla"

Islamic calendar, tabular (intercalary years [2,5,7,10,13,16,18,21,24,26,29] - astronomical epoch)

`ISLAMIC_UMALQURA`

CalendarIdentifier.ISLAMIC_UMALQURA ＝ "islamic-umalqura"

Islamic calendar, Umm al-Qura

`ISO8601`

CalendarIdentifier.ISO8601 ＝ "iso8601"

ISO calendar (Gregorian calendar using the ISO 8601 calendar week rules)

`JAPANESE`

CalendarIdentifier.JAPANESE ＝ "japanese"

Japanese imperial calendar

`PERSIAN`

CalendarIdentifier.PERSIAN ＝ "persian"

Persian calendar

`ROC`

CalendarIdentifier.ROC ＝ "roc"

Civil (algorithmic) Arabic calendar

`Weekday`

Android

iOS

tvOS

Web

An enum mapping days of the week in Gregorian calendar to their index as returned by the firstWeekday property.

`SUNDAY`

Weekday.SUNDAY ＝ 1

`MONDAY`

Weekday.MONDAY ＝ 2

`TUESDAY`

Weekday.TUESDAY ＝ 3

`WEDNESDAY`

Weekday.WEDNESDAY ＝ 4

`THURSDAY`

Weekday.THURSDAY ＝ 5

`FRIDAY`

Weekday.FRIDAY ＝ 6

`SATURDAY`

Weekday.SATURDAY ＝ 7