react-native-i18n/README.md

219 lines
5.1 KiB
Markdown
Raw Normal View History

2017-05-25 16:06:06 +00:00
<img src="https://cdn0.iconfinder.com/data/icons/material-design-ii-glyph/614/3010_-_Translate-512.png" width="100" align="left" />
2017-05-23 09:17:42 +00:00
2015-06-14 15:09:32 +00:00
# react-native-i18n
2017-05-25 16:06:06 +00:00
2017-06-09 09:03:59 +00:00
Integrates [I18n.js](https://github.com/fnando/i18n-js) with React Native. Uses the user preferred locale as default.
2016-08-18 12:58:33 +00:00
<br/>
<br/>
2015-06-14 15:09:32 +00:00
2017-01-26 09:23:37 +00:00
## Installation
2017-05-25 16:06:06 +00:00
2017-06-26 20:25:56 +00:00
**Using yarn (recommended)**
2017-06-26 08:58:34 +00:00
`$ yarn add react-native-i18n`
2017-05-25 16:06:06 +00:00
**Using npm**
`$ npm install react-native-i18n --save`
2017-06-26 20:25:08 +00:00
:warning: npm currently has an issue resolving git sub-dependencies.
2017-06-26 08:58:34 +00:00
Check [this issue](https://github.com/AlexanderZaytsev/react-native-i18n/issues/101) for more informations.
2016-08-18 12:58:33 +00:00
## Automatic setup
2017-05-25 16:06:06 +00:00
After installing the npm package you need to link the native modules.
If you're using React-Native < 0.29, install [rnpm](https://github.com/rnpm/rnpm) with the command `npm install -g rnpm` and then link the library with the command `rnpm link`.
2016-08-18 12:28:57 +00:00
If you're using React-Native >= 0.29 just link the library with the command `react-native link`.
2016-03-08 21:25:55 +00:00
2016-08-18 12:50:08 +00:00
If you're having any issue you can also try to install the library manually as follows.
2017-06-26 10:00:46 +00:00
## Automatic setup with Cocoapods
2017-06-26 20:24:07 +00:00
After installing the npm package, add the following line to your Podfile
2017-06-26 10:00:46 +00:00
2017-06-26 20:24:07 +00:00
```ruby
2017-07-10 19:06:22 +00:00
pod 'RNI18n', :path => '../node_modules/react-native-i18n'
2017-06-26 10:00:46 +00:00
```
2017-06-26 20:24:07 +00:00
and run
2017-06-26 10:00:46 +00:00
```
2017-06-26 20:24:07 +00:00
pod install
2017-06-26 10:00:46 +00:00
```
## Manual setup
2017-05-25 16:06:06 +00:00
2016-08-18 12:58:33 +00:00
### iOS
2017-05-25 16:06:06 +00:00
2016-08-18 12:58:33 +00:00
Add `RNI18n.xcodeproj` to **Libraries** and add `libRNI18n.a` to **Link Binary With Libraries** under **Build Phases**.
[More info and screenshots about how to do this is available in the React Native documentation](http://facebook.github.io/react-native/docs/linking-libraries-ios.html#content).
2015-06-14 15:09:32 +00:00
2017-06-09 09:03:59 +00:00
You also need to add the **localizations** you intend to support to your iOS project. To do that open your Xcode project:
```
$ open <your-project>.xcodeproj
```
2017-05-25 16:06:06 +00:00
And add the localizations you will support as shown here:
2017-06-15 05:08:24 +00:00
![adding locales](https://github.com/AlexanderZaytsev/react-native-i18n/blob/master/docs/adding-locales.png?raw=true)
### Android
2017-05-25 16:06:06 +00:00
Add `react-native-i18n` to your `./android/settings.gradle` file as follows:
2017-05-25 16:06:06 +00:00
2017-06-26 20:24:07 +00:00
```gradle
include ':app', ':react-native-i18n'
project(':react-native-i18n').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-i18n/android')
```
Include it as dependency in `./android/app/build.gradle` file:
2017-05-25 16:06:06 +00:00
2017-06-26 20:24:07 +00:00
```gradle
dependencies {
2017-06-26 20:24:07 +00:00
// ...
compile project(':react-native-i18n')
}
```
2016-08-18 12:50:08 +00:00
Finally, you need to add the package to your MainApplication (`./android/app/src/main/java/your/bundle/MainApplication.java`):
2017-05-25 16:06:06 +00:00
```java
2017-05-25 16:06:06 +00:00
import com.AlexanderZaytsev.RNI18n.RNI18nPackage; // <-- Add to ReactNativeI18n to the imports
2017-06-26 20:24:07 +00:00
// ...
@Override
2016-08-18 12:50:08 +00:00
protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
new MainReactPackage(),
2017-06-26 20:24:07 +00:00
// ...
2017-05-25 16:06:06 +00:00
new RNI18nPackage(), // <-- Add it to the packages list
);
}
2017-06-26 20:24:07 +00:00
// ...
```
After that, you will need to recompile your project with `react-native run-android`.
2017-06-09 09:03:59 +00:00
**Note: You'll need to install Android build tools 25.0.2**
2017-05-25 16:06:06 +00:00
2017-06-26 08:59:26 +00:00
![android install](https://github.com/AlexanderZaytsev/react-native-i18n/blob/master/docs/android-install.png?raw=true)
2017-06-26 08:58:34 +00:00
2015-06-14 15:09:32 +00:00
## Usage
2017-06-26 20:24:07 +00:00
2016-08-18 12:28:57 +00:00
```javascript
import I18n from 'react-native-i18n'
2015-06-14 15:09:32 +00:00
2016-08-18 12:28:57 +00:00
class Demo extends React.Component {
render () {
2015-06-14 15:09:32 +00:00
return (
<Text>{I18n.t('greeting')}</Text>
)
}
2016-08-18 12:28:57 +00:00
}
2015-06-14 15:09:32 +00:00
2015-07-09 04:29:49 +00:00
// Enable fallbacks if you want `en-US` and `en-GB` to fallback to `en`
2016-08-18 12:28:57 +00:00
I18n.fallbacks = true
2015-07-09 04:29:49 +00:00
2015-06-14 15:09:32 +00:00
I18n.translations = {
en: {
greeting: 'Hi!'
},
fr: {
greeting: 'Bonjour!'
}
}
```
2015-06-14 15:12:16 +00:00
This will render `Hi!` for devices with the English locale, and `Bonjour!` for devices with the French locale.
## Usage with multiple location files
2017-06-09 09:03:59 +00:00
```javascript
// app/i18n/locales/en.js
2017-06-09 09:03:59 +00:00
export default {
greeting: 'Hi!'
};
// app/i18n/locales/fr.js
2017-06-09 09:03:59 +00:00
export default {
greeting: 'Bonjour!'
};
// app/i18n/i18n.js
2017-06-09 09:03:59 +00:00
import I18n from 'react-native-i18n';
import en from './locales/en';
import fr from './locales/fr';
I18n.fallbacks = true;
I18n.translations = {
en,
fr
};
export default I18n;
2017-06-09 09:03:59 +00:00
// usage in component
import I18n from 'app/i18n/i18n';
class Demo extends React.Component {
render () {
return (
<Text>{I18n.t('greeting')}</Text>
)
}
}
```
2015-07-09 04:29:49 +00:00
### Fallbacks
When fallbacks are enabled (which is generally recommended), `i18n.js` will try to look up translations in the following order (for a device with `en_US` locale):
- en-US
- en
2017-06-09 09:03:59 +00:00
**Note**: iOS 8 locales use underscored (`en_US`) but `i18n.js` locales are dasherized (`en-US`). This conversion is done automatically for you.
2017-06-26 20:24:07 +00:00
```javascript
2016-08-18 12:28:57 +00:00
I18n.fallbacks = true
2015-07-09 04:29:49 +00:00
I18n.translations = {
'en': {
greeting: 'Hi!'
},
'en-GB': {
greeting: 'Hi from the UK!'
}
}
```
2017-06-09 09:03:59 +00:00
2015-07-09 04:29:49 +00:00
For a device with a `en_GB` locale this will return `Hi from the UK!'`, for a device with a `en_US` locale it will return `Hi!`.
2015-06-14 15:09:32 +00:00
2017-06-15 05:34:14 +00:00
### Device's locales
2017-06-09 09:03:59 +00:00
2017-06-15 05:34:14 +00:00
You can get the user preferred locales with the `getLanguages` method:
2017-06-09 09:03:59 +00:00
2017-06-26 20:24:07 +00:00
```javascript
2017-06-09 09:03:59 +00:00
import { getLanguages } from 'react-native-i18n'
getLanguages().then(languages => {
2017-06-15 05:34:14 +00:00
console.log(languages) // ['en-US', 'en']
2017-06-09 09:03:59 +00:00
})
```
2015-07-09 04:29:49 +00:00
### I18n.js documentation
2017-06-09 09:03:59 +00:00
2015-07-09 04:29:49 +00:00
For more info about I18n.js methods (`localize`, `pluralize`, etc) and settings see [its documentation](https://github.com/fnando/i18n-js#setting-up).
2015-06-14 15:21:55 +00:00
## Licence
2017-06-09 09:03:59 +00:00
2015-07-09 04:29:49 +00:00
MIT