Expo 本土化

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

Android

iOS

tvOS

Web

expo-localization 允许你本地化你的应用，为特定地区、语言或文化定制体验。它还提供对原生设备上的区域设置数据的访问。使用本地化库（例如 lingui-js、react-i18next、react-intl 或 i18n-js）和 expo-localization 将使你能够为用户创建非常方便的体验。

¥expo-localization allows you to Localize your app, customizing the experience for specific regions, languages, or cultures. It also provides access to the locale data on the native device. Using a localization library such as lingui-js, react-i18next, react-intl or i18n-js with expo-localization will enable you to create a very accessible experience for users.

安装

¥Installation

Terminal

- npx expo install expo-localization

If you are installing this in an existing React Native app (bare workflow), start by installing expo in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.

app.json/app.config.js 中的配置

¥Configuration in app.json/app.config.js

如果你在项目中使用配置插件（EAS 构建或 npx expo run:[android|ios]），则可以使用其内置的配置插件配置 expo-localization。该插件允许你配置无法在运行时设置的各种属性，并且需要构建新的应用二进制文件才能生效。

¥You can configure expo-localization using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": ["expo-localization"]
  }
}

用法

¥Usage

在本土化指南中查找有关使用 expo-localization 和添加对从右到左语言的支持的更多信息。

¥Find more information about using expo-localization and adding support for right-to-left languages in the Localization guide.

API

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

行为

¥Behavior

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

¥You can use synchronous getLocales() and getCalendars() methods to get the locale settings of the user device. On iOS, the results will remain the same while the app is running.

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

¥On Android, the user can change locale preferences in Settings without restarting apps. To keep the localization current, you can rerun the getLocales() and getCalendars() methods every time the app returns to the foreground. Use AppState to detect this.

Constants

Deprecated Use Localization.getLocales() instead. An IETF BCP 47 language tag, consisting of a two-character language code and optional script, region and variant codes.

`Localization.locale`

Type: string

Example

'en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng'

Hooks

`useCalendars()`

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[]

Example

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

`useLocales()`

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[]

Example

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

Methods

`Localization.getCalendars()`

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[]

Example

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

`Localization.getLocales()`

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[]

Example

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

Types

`Calendar`

Name	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`

Name	Type	Description
currencyCode	`string \| null`	Currency code for the locale. Is `null` on Web, use a table lookup based on region instead. Example `'USD'`, `'EUR'`, `'PLN'`.
currencySymbol	`string \| null`	Currency symbol for the locale. Is `null` on Web, use a table lookup based on region (if available) instead. 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'`.
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).
temperatureUnit	`'celsius' \| 'fahrenheit' \| null`	The temperature unit used in the locale. Returns `null` if the region code is unknown.
textDirection	`'ltr' \| 'rtl' \| null`	Text direction for the locale. One of: `'ltr'`, `'rtl'`, but can also be `null` on some browsers without support for the textInfo property in Intl API.

`Localization`

Name	Type	Description
currency	`string \| null`	Three-character ISO 4217 currency code. Returns `null` on web. Example `'USD'`, `'EUR'`, `'CNY'`, `null`
decimalSeparator	`string`	Decimal separator used for formatting numbers. Example `','`, `'.'`
digitGroupingSeparator	`string`	Digit grouping separator used when formatting numbers larger than 1000. Example `'.'`, `''`, `','`
isMetric	`boolean`	Boolean value that indicates whether the system uses the metric system. On Android and web, this is inferred from the current region.
isRTL	`boolean`	Returns if the system's language is written from Right-to-Left. This can be used to build features like bidirectional icons. Returns `false` in Server Side Rendering (SSR) environments.
isoCurrencyCodes	`string[]`	A list of all the supported language ISO codes.
locale	`string`	An IETF BCP 47 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'`
locales	`string[]`	List of all the native languages provided by the user settings. These are returned in the order that the user defined in the device settings. Example `['en', 'en-US', 'zh-Hans', 'zh-Hans-CN', 'en-emodeng']`
region	`string \| null`	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`
timezone	`string`	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'`