react-native-intl
Native Intl implementation and Translation extension. The extension loads translation catalog from gettext .mo
files. Note that PO files are not supported.
Please note this version only supports React Native 0.19 and newer.
Features
- Collator
Not yet supported - DateTimeFormat
Constructor for objects that format dates and times to match a specified locale. - NumberFormat
Constructor for objects that format numbers to match a specified locale. - Translation (not a part of ECMAScript)
Constructor for objects that translate messages into another languages using.mo
files.
Installation
$ npm install react-native-intl-plus --save
iOS Setup
Once you've installed the module, you need to integrate it into the Xcode project of your React Native app. To do this, do the following steps.
- Open your app's Xcode project
- Find
RNIntl.xcodeproj
file within thenode_modules/react-native-intl
directory, and drag it intoLibraries
category in Xcode. - Go to the "Build Phases" tab in your project configuration.
- Drag
libRNIntl.a
fromLibraries/RNIntl.xcodeproj
into the "Link Binary With Libraries" section of your project's "Build Phases" configuration. - To translate messages, create
i18n
folder and put.mo
files into it. Drag the folder to just below the project in Xcode. Choose Create folder references.
Android Setup
In order to use this module in your Android project, take the following steps.
- In your
android/settings.gradle
file, add the following code:
include ':rnintl'
project(':rnintl').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-intl/android')
- In your
android/app/build.gradle
file, add:react-native-intl
project as a dependency (note that app folder):
...
dependencies {
...
compile project(':rnintl')
}
- Update your
MainActivity.java
file to look like this (without preceding the+
signs).
package com.myapp; + import kim.taegon.rnintl.ReactNativeIntlPackage; .... public class MainActivity extends Activity implements DefaultHardwareBackBtnHandler { private ReactInstanceManager mReactInstanceManager; private ReactRootView mReactRootView; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); mReactRootView = new ReactRootView(this); mReactInstanceManager = ReactInstanceManager.builder() .setApplication(getApplication()) .setBundleAssetName("index.android.bundle") .setJSMainModuleName("index.android") .addPackage(new MainReactPackage())+ .addPackage(new ReactNativeIntlPackage()) .setUseDeveloperSupport(BuildConfig.DEBUG) .setInitialLifecycleState(LifecycleState.RESUMED) .build(); mReactRootView.startReactApplication(mReactInstanceManager, "MyApp", null); setContentView(mReactRootView); } ... }
- To translate messages, create
i18n
folder and put.mo
files into it. Then, copy/link the folder intoandroid/app/src/main/assets
. You may need to create theassets
folder.
API
- DateTimeFormat objects are similar to JavaScript Intl.DateTimeFormat except
format
method returns a Promise. - NumberFormat objects are similar to JavaScript Intl.NumberFormat except
format
method returns a Promise. - Translation objects load translation catalog from local file system and translates the passed message into another language. It also supports plural forms.
-
Constructor can take a locale identifier as an argument.
new Intl.Translation([locale])
-
getTranslator
returns a Promise that passes the message translator function which takes two arguments, message id and optional plural counter. If the function can't find any proper string, it returns the message id.new Intl.Translation().getTranslator().then( _ => { console.log( _("Hello, world") ); }); // or you can use await syntax const _ = await new Intl.Translation().getTranslator(); console.log( _("Hello, world") );
-
How to format dates/numbers
Load react-native-intl
module in your JavaScript code.
const Intl = require('react-native-intl');
Like the JavaScript objects, create an instance with/without a locale identifier and call its format
method. Unlike JavaScript, the method returns a Promise because React Native's JS-Native bridge should work asynchronous.
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
new Intl.DateTimeFormat('en-US').format(date).then(
str => console.log(str)
);
If you omit the locale identifier, system locale will be used by default.
How to translate messages
Load react-native-intl
module in your JavaScript code and create a translation instance with your locale. Get a translator function through the promise getTranslator()
returned and call it to get translated messages. The translator function works like ngettext, you can pass a plural counter to it.
const Intl = ;const french = 'fr-FR'; french;
.mo
files?
Why gettext Although I prefer to use json
format in most cases, mo
format is better as it supports plural form and context. I don't want to embed po
files in my app due to its bigger footprint.
Notes
Because of the difference of platforms, some features can be limited based on platform. The following table shows what features supported on each platform.
Feature | iOS | Android |
---|---|---|
Collator | x | x |
DateTimeFormat | △ | △ |
- numbering system | x | x |
- calendar | o | x |
- resolveOptions() | x | x |
- options | △ | △ |
-- locale matcher | x | x |
-- format matcher | x | x |
-- hour12 | x | x |
-- all other options | o | o |
NumberFormat | △ | △ |
- numbering system | x | x |
- resolveOptions() | x | x |
- options | △ | △ |
-- locale matcher | x | x |
-- currencyDisplay | x | x |
-- minimumSignificantDigits | o | x |
-- maximumSignificantDigits | o | x |
-- all other options | o | o |
Translation | o | o |
Feedback
This project is in early stage and I'm very new in both native platforms and even the programming languages. In fact, I've created this module learning them from basic syntax. So, the code may not be fine, unsafe or insecure.
I will welcome any contributions from you including pull requests, bug reports, suggestions and even English correction. Don't hesitate to leave your feedback.