react-native-localization-settings
v1.2.0
Published
React Native module to expose per-app language preferences API on iOS and Android.
Downloads
21,525
Readme
React Native Localization Settings
react-native-localization-settings
is a native module to expose per-app language preferences API on iOS and Android.
Supported platforms
| Platform | Supported | |----------|:---------:| | iOS | ✅ | | Android* | ✅ |
*per-app language settings was introduced in API level 33 (Android 13). On the older versions, the library uses SharedPreferences to store the language.
Installation
To get started with react-native-localization-settings
, you'll need to install it using npm:
npm install react-native-localization-settings
or with yarn:
yarn add react-native-localization-settings
Setup
To get started, define the languages your app will support. If you're using Expo, you can leverage the Expo config plugin to generate the necessary native configurations.
Expo
Simply add the config plugin to your app.json
file and specify the list of supported languages:
{
"expo": {
// ...
"plugins": [
[
"react-native-localization-settings",
{
"languages": ["en", "pl"]
}
]
]
}
}
and run npx expo prebuild
.
Bare react-native app
If your app isn’t using Expo, you’ll need to add the configuration manually.
Next, you need to create a Localization.strings
file.
Select newly created file and on the right side of the screen, under Localizations
selection press Localize
. Confirm
the popup.
Lastly, you need to select all elements in the section form previous step.
<?xml version="1.0" encoding="utf-8"?>
<locale-config xmlns:android="http://schemas.android.com/apk/res/android">
<locale android:name="en"/>
<locale android:name="pl"/>
<locale android:name="fr"/>
</locale-config>
Then, open android/app/src/main/AndroidManifest.xml
and add following line to the Application tag:
<application
android:name=".MainApplication"
android:localeConfig="@xml/locales_config" <!-- this line -->
>
API
getLanguage()
Function to get current language.
Returns Language in IETF BCP 47 format (like 'en-US')
getLanguage(); // 'en-US'
setLanguage()
Function to set the current language. It accepts a string with language code in IETF BCP 47 format (like 'en-US') or ISO 639-1 format (like 'en').
setLanguage("en-US");
i18next
This library is fully compatible with i18next.
To use it with i18next, create a language detector by using createLanguageDetector
with the specified options
:
import { createLanguageDetector } from 'react-native-localization-settings';
const languageDetector = createLanguageDetector({});
i18next
.use(languageDetector)
.use(initReactI18next)
.init({
// ...
});
Options
type LanguageDetectorOptions = {
cacheCurrentLanguage?: boolean; // default: false - sets current detected language
async?: boolean; // default: false - uses getLanguageAsync (set to true on old architecture)
};
Changing language
Then, if you want to create custom in-app language selector, you should be able to change the language (along with the settings per-app language) using standard i18next function:
i18next.changeLanguage('pl-PL');
Why?
Users who speak multiple languages often set their device language to one language, such as English, but they may want to use other languages for certain apps, like Polish, Dutch, or French. To help apps provide a better experience for these users, this package adds the ability to set language preferences for individual apps in the device's settings.
License
Made with ❤️ by Jakub Grzywacz