https://github.com/gandi/react-translate
I18N libraries and tools for your react application.
https://github.com/gandi/react-translate
Last synced: about 1 year ago
JSON representation
I18N libraries and tools for your react application.
- Host: GitHub
- URL: https://github.com/gandi/react-translate
- Owner: Gandi
- License: isc
- Created: 2016-11-17T16:06:11.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-10-11T07:27:28.000Z (over 7 years ago)
- Last Synced: 2025-04-12T03:15:08.657Z (about 1 year ago)
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@gandi/react-translate
- Size: 82 KB
- Stars: 13
- Watchers: 24
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
**// DEPRECATED: please consider to use [linguijs](https://lingui.js.org/) or other alternatives.**
# @gandi/react-translate
>I18N libraries and tools for your react application.
[](https://travis-ci.org/Gandi/react-translate)
[](https://www.npmjs.com/package/@gandi/react-translate)
[](https://www.npmjs.com/package/@gandi/react-translate)
[](https://webchat.freenode.net/)
**Features:**
* String localization with [counterpart](https://github.com/martinandert/counterpart);
* Messages extraction;
* Catalogs management (similar to [gettext](https://en.wikipedia.org/wiki/Gettext));
* Date & Time formats with [momentjs](http://momentjs.com/);
* Prices and number format with [intljs](https://github.com/andyearnshaw/Intl.js);
* Several components & functions.
## Installation
```
npm install --save @gandi/react-translate
```
Add the following script to your `package.json`, it's a simple shortcut for extraction
scripts:
```
// ...
"scripts": {
// ...
"i18n": "react-translate-scripts"
}
```
Extraction script requires `babel-cli`, `babel-gettext-plugin` and `po2json` in your dependencies
(it's up to you to select the version saved in your project):
```
npm install --save-dev babel-cli babel-gettext-plugin po2json
```
## Usage
### 1. init: `provideTranslate`
Provide some helpers functions in the React context.
It's up to you to load `translations` from the json generated by scripts (cf.
[How to create language files]). So you will be able to promise a json object or preload translations
directly in the DOM (e.g. via server side rendering).
```javascript
import { provideTranslate, createTranslator } from '@gandi/react-translate';
const translatorParams = {
translations: { // catalog
'This is a test %(username)s!': 'C\'est un test %(username)s!',
},
locale: 'fr', // user's locale
utcOffset: 0, // user's zone offset
defaultLocale: 'en', // default application locale
logMissing: false, // display warnings when translations are missing (except on production)
localeData: { // IntlPolyfill localeData configuration
locale: 'fr',
number: {
currencies: {
USD: '$US',
EUR: '€',
},
},
},
};
const translator = createTranslator(translatorParams);
@provideTranslate(translator)
class App {
render() {
...
}
}
```
### 2. Implementation: `withTranslator(options)`
Inject helpers into the components props from context variables.
```javascript
import React, { Component, PropTypes } from 'react';
import { withTranslator } from '@gandi/react-translate';
@withTranslator()
class MyComponent extends Component {
static propTypes = {
__: PropTypes.func.isRequired,
};
static preFetch({ __ }) {
console.log(__('So i18n'));
}
render() {
const { __ } = this.props;
return (
{ __('So i18n') });
}
}
```
In order to prevent the [unknown props warning](https://facebook.github.io/react/warnings/unknown-prop.html)
(and non-standard DOM attributes):
```javascript
bundle.js:2009 Warning: Unknown props `formatDate`, `formatNumber`, `formatPrice`, `formatCurrency`, `localize`
on tag. Remove these props from the element. For details, see https://fb.me/react-unknown-prop
```
you can use the `propsNamespace` option:
```javascript
@withTranslator({ propsNamespace: 'translator' })
class Presenter extends React.Component {
static propTypes = {
translator: PropTypes.shape({ __: PropTypes.func.isRequired }),
};
render() {
const { translator: { __ }, ...props } = this.props;
return {__('foobar')};
}
}
```
## 3. Create language files
This library uses babel and the plugin
[babel-gettext-plugin](https://www.npmjs.com/package/babel-gettext-plugin) to extract your
internationalized strings.
> In case you created your app with create-react-app you have to declare the babel preset you need
to build your application, for example:
```json
// file:.babelrc
{
"presets": ["react"]
}
```
### Message files
First create a template message file with all the translation strings in a json:
```bash
npm run i18n extract_messages [folder/to/extract] [namespace]
```
_(All commands are launched from the root directory of your node project.)_
### Catalogs
A catalog file is a json file, representing a single language.
Before the first run you'll need to create one folder per needed locale, for instance:
```bash
mkdir locales/{fr,it,es}
```
After you created your message file – **and each time you make changes to it** – you’ll need to
create or update the catalogs:
```bash
npm run i18n create_catalog && npm run i18n update_catalog
```
Sometimes you must clean the catalogs by running this command:
```bash
npm run i18n clean_catalog
```
> Tips: In case you use a tool like weblate, you may not clean every time you are extracting
> messages or updating catalogs to avoid losing old translations that could be used by the tool to
> suggest translations.
## Documentation
* [Translator (aka `__`)](doc/translator.md)
* [Date/Time (aka `localize`)](doc/localize.md)
* [Pricing (aka prize)](doc/prize.md)
* [formatCurrency (aka MapCurrencyISOToSymbol)](doc/formatCurrency.md)
* [Number formatting (aka formatNumber)](doc/formatNumber.md)
## Tests
More in [testing documentation](doc/testing.md).
You have various ways to stub your translator.
```javascript
import { createTranslateContext, createTranslateContextTypes }
from '@gandi/react-translate/dist/test';
describe('...', () => {
it('...', () => {
const wrapper = mount(, {
context: createTranslateContext(),
childContextTypes: createTranslateContextTypes(),
});
});
});
```
```javascript
import { stubProvideTranslate } from '@gandi/react-translate/dist/test';
describe('LocalLoader component', () => {
it('should render a spinner', () => {
const LocalLoader_ = stubProvideTranslate({ locale: 'fr' })(LocalLoader);
// ...
});
});
```
## Components examples
`@gandi/react-translate` comes bundled wit some components:
```jsx
1982-03-28 12:00:00 UTC
1982-03-28 12:00:00 UTC
```
To use localization programmatically, just do:
```javascript
import React, { Component, PropTypes } from 'react';
import { withTranslator } from '@gandi/react-translate';
@withTranslator()
class MyComponent extends Component {
static propTypes = {
localize: PropTypes.func.isRequired,
};
static preFetch({ localize }) {
console.log(localize(new Date()).format('LLLL'));
}
render() {
const { localize } = this.props;
return (
{ localize(new Date()).format('LLLL') });
}
}
```
## App samples
Check the samples/app directory to see a "real" application in action.
```bash
cd samples/app
npm i
npm run start
```
## Change Log
All notable changes to this project will be documented in [this section](CHANGELOG.md).
*This project adheres to [Semantic Versioning](http://semver.org/) and [Keep A Changelog](http://keepachangelog.com/).*
## Patrons
The work on this project was possible thanks to [Gandi.net](https://gandi.net) (#no_bullshit).
## Found a bug or contribute?
Please open an [issue](https://github.com/Gandi/react-translate/issues). If it's clear and well
labelized, it's quicker to fix!
Else you can start with [CONTRIBUTING.md](CONTRIBUTING.md).
## TODO
* Document `Pricing` features
* Add formatCurrency component
* Improve doc on how to load translations (at least give an example)
* Link translator options to related libs
* Allow user to init a logger for missing translations and use `warning` as fallback
* Fix or change build process in `bin/merge_catalogs` which looks for legacy gandi's catalogs