Merge branch 'release/1.0.0'

eugene-manuilov · Jul 16, 2019 · 5c4f464 · 5c4f464
2 parents 9ec8831 + 23dc246
commit 5c4f464
Show file tree

Hide file tree

Showing 32 changed files with 20,690 additions and 11,923 deletions.
diff --git a/.babelrc b/.babelrc
diff --git a/.eslintrc b/.eslintrc
diff --git a/.travis.yml b/.travis.yml
@@ -1,5 +1,5 @@
 language: node_js
 node_js:
-  - "6"
+  - "10"
 script:
   - "npm test"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Change Log
 
+## v1.0.0 (2019-07-15)
+
+- Implemented TextdomainContext context that adheres the current version of Context APIs.
+- Reworked Poedit example project to use new API.
+
 ## v0.4.0 (2017-08-17)
 
 **Implemented enhancements:**

diff --git a/README.md b/README.md
@@ -1,22 +1,98 @@
-# react-gettext 0.4.0
+# react-gettext 1.0.0
 
 [![npm version](https://badge.fury.io/js/react-gettext.svg)](https://badge.fury.io/js/react-gettext) [![Build Status](https://travis-ci.org/eugene-manuilov/react-gettext.svg?branch=master)](https://travis-ci.org/eugene-manuilov/react-gettext)
 
-Tiny React library for implementing gettext localization in your application. It provides HOC function to enhance your application by exposing gettext functions in the context scope.
+A tiny React library that helps to implement internalization in your application using gettext functions. It uses [React Context API](https://reactjs.org/docs/context.html) to expose gettext functions to children components.
 
 ## Instalation
 
-React Gettext requires **React 15.0 or later**. You can add this package using following commands:
+> **Note:** This library requires **React 16.3 or later**
 
 ```
-npm install react-gettext --save
+npm i react react-gettext
 ```
 
+## Usage
+
+To use this library in your application, you need to do a few simple steps:
+
+1. Prepare translations and define plural form functions.
+1. Add `TextdomainContext.Provider` provider to the root of your application.
+1. Updated your components to use context functions, provided by `TextdomainContext`, to translate text messages.
+
+Let's take a closer look at each step. First of all, you to create translation catalogs and prepare plural form functions for every language that you are going to use. Each language needs one catalog and one plural form function. 
+
+The translation catalog is an object that contains key/value pairs where keys are original singular messages and values are translations. If you have a message that can have plural forms, the value for it should be an array with translations where each translation corresponds to appropriate plural form. Finally, if you want to use a context with your messages, then it should be prepended to the message itself and separated by using `\u0004` (end of transition) character. Here is an example:
+
+```javascript
+{
+	"Hello world!": "¡Hola Mundo!", // regular message
+	"article": ["artículo", "artículos"], // plural version
+	"Logo link\u0004Homepage": "Página principal", // single message with "Logo link" contex
+	"Search results count\u0004article": ["artículo", "artículos"], // plural version with "Search results count" context
+}
 ```
-yarn add react-gettext
+
+The plural form function is a function that determines the number of a plural form that should be used for a particular translation. For English, the plural form is `n != 1 ? 1 : 0`, that means to use a translation with `0` index when `n == 1`, and a translation with `1` index in all other cases. Slavic and arabic languages have more than 2 plural forms and their functions are more complicated. Translate Toolkit has a [list of plural forms expressions for many languages](http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms) that you can use in your project. An example of a plural form function can be the following:
+
+```javascript
+function getPluralForm(n) {
+    return n != 1 ? 1 : 0;
+}
 ```
 
-## Usage
+The next step is to pass translations and plural form function for the current language to the `buildTextdomain` function. It will create APIs that need to be passed to the `TextdomainContext.Provider` provider that you need to add to the root of your project:
+
+```javascript
+import React, { Component } from 'react';
+import { TextdomainContext, buildTextdomain } from 'react-gettext';
+
+class MyApp extends Component {
+
+    constructor(props) {
+        super(props);
+        this.state = { textdomain: buildTextdomain(...) };
+    }
+
+    render() {
+        return (
+            <div>
+                <TextdomainContext.Provider value={this.state.textdomain}>
+                    <ComponentA />
+                    ...
+                </TextdomainContext>
+            </div>
+        );
+    }
+
+}
+```
+
+> **Note:** Please, pay attention that you need to avoid passing the results of `buildTextdomain` function directly into `TextdomainContext.Provider`'s value to escape unintentional renders in consumers when a provider’s parent re-renders.
+
+Finally, the last step is to update your descendant components to consume these context APIs. Import `TexdomainContext` in the child component and assign it to the component `contextType` static properly. It will expose gettext APIs to that component via `this.context` field:
+
+
+```javascript
+import React, { Component } from 'react';
+import { TextdomainContext } from 'react-gettext';
+
+class ComponentA extends Component {
+
+    render() {
+        const { gettext, ngettext, xgettext, nxgettext } = this.context;
+
+        return (
+            <div>...</div>
+        );
+    }
+
+}
+
+ComponentA.contextType = TextdomainContext;
+```
+
+## An example
 
 Let's assume you have following React application:
 
@@ -56,115 +132,83 @@ export default class Header extends Component {
 }
 ```
 
-To make it translatable you need to update your `app.js` file to use HOC function and export higher-order component:
+To make it translatable, you need to update your `app.js` file to use TextdomainContext provider and build textdomain using messages list and plural form function:
 
 ```diff
   // app.js
   import React, { Component } from 'react';
-+ import withGettext from 'react-gettext';
++ import { TextdomainContext, buildTextdomain } from 'react-gettext';
   import Header from './Header';
   import Footer from './Footer';
 
-- export default class App extends Component {
-+ class App extends Component {
-      ...
-  }
+  export default class App extends Component {
+
++     constructor(props) {
++         super(props);
++         this.state = {
++             textdomain: buildTextdomain(
++                 {
++                     'Welcome to my application!': 'Bienvenido a mi aplicación!',
++                     // ...
++                 },
++                 n => n != 1
++             ),
++         };
++     }
 
-+ export default withGettext({...}, 'n != 1')(App);
+      render() {
+          return (
+              <div id="app">
++                 <TextdomainContext.Provider value={this.state.textdomain}>
+                      <Header />
+                      ...
+                      <Footer />
++                 </TextdomainContext.Provider>
+              </div>
+          );
+      }
+  }
 ```
 
 After doing it you can start using `gettext`, `ngettext`, `xgettext` and `nxgettext` functions in your descending components:
 
 ```diff
   // Header.js
-- import React, { Component } from 'react';
-+ import React, { Component } from 'react';
-+ import PropTypes from 'prop-types';
+  import React, { Component } from 'react';
++ import { TextdomainContext } from 'react-gettext';
 
   export default class Header extends Component {
 
       render() {
++         const { gettext } = this.context;
           return (
 -             <h1>Welcome to my application!</h1>
-+             <h1>{this.context.gettext('Welcome to my application!')}</h1>
++             <h1>{gettext('Welcome to my application!')}</h1>
           );
       }
 
   }
 
-+ Header.contextTypes = {
-+     gettext: PropTypes.func.isRequired,
-+     ngettext: PropTypes.func.isRequired,
-+     xgettext: PropTypes.func.isRequired,
-+     nxgettext: PropTypes.func.isRequired,
-+ };
++ Header.contextType = TextdomainContext;
 ```
 
-See an [example](https://github.com/eugene-manuilov/react-gettext/tree/master/examples) application to get better understanding how to use it.
+Check a [sample](https://github.com/eugene-manuilov/react-gettext/tree/master/examples/poedit) application to see how it works.
 
 ## Documentation
 
-### withGettext(translations, pluralForms, options)
-
-Higher-order function which is exported by default from `react-gettext` package. It accepts two arguments and returns function to create higher-order component.
-
-- **translations**: a hash object or a function which returns hash object where keys are original messages and values are translated messages.
-- **pluralForms**: a string to calculate plural form (used by [Gettext PO](http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms)) or a function which accepts a number and calculates a plural form number. Pay attentions that plural forms are zero-based what means to get 1st plural form it should return 0, to get 2nd - 1, and so on.
-- **options**: a hash object with options. Currently supports following options:
-  - **withRef**: an optional boolean flag that determines whether or not to set `ref` property to a wrapped component what will allow you to get wrapped component instance by calling `getWrappedComponent()` function of the HOC. By default: `FALSE`.
-
-Example:
-
-```javascript
-const translations = {
-    'Some text': 'Some translated text',
-    ...
-};
+### buildTextdomain(translations, pluralForm)
 
-const pluralForms = '(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)'; // 3 plural forms for Russian, Belarusian, Bosnian, Croatian, Serbian, Ukrainian, etc.
+Builds gettext APIs for TextdomainContext provider that will work with provided translations.
 
-const HOC = withGettext(translations, pluralForms)(App);
-```
+- **translations**: an object with translated messages.
+- **pluralForm**: a function that determines a plural form or a stringular reresentation of it.
 
 ```javascript
-function getTranslations() {
-    return {
-        'Some text': 'Some translated text',
-        ...
-    };
-}
-
-function getPluralForms(n) {
-    return n > 1 ? 1 : 0;
-}
-
-const HOC = withGettext(getTranslations, getPluralForms)(App);
+const api = buildTextdomain( { ... }, n => n == 1 ? 0 : 1 );
+// or
+const api = buildTextdomain( { ... }, 'n == 1 ? 0 : 1' );
 ```
 
-As an alternative you can pass translations and plural form as properties to higher-order-component, like this:
-
-```javascript
-function getTranslations() {
-    return {
-        'Some text': 'Some translated text',
-        ...
-    };
-}
-
-function getPluralForms(n) {
-    return n > 1 ? 1 : 0;
-}
-
-const HOC = withGettext()(App);
-
-...
-
-ReactDOM.render(<HOC translations={getTranslations} plural={getPluralForms}>...</HOC>, ...);
-```
-
-One more alternative is to not create HOC, but use Textdomain component directly. You can import it using `import { Textdomain } from 'react-gettext'` and use it as a regular component which will provide context functions to translate your messages. Just don't forget to pass `translations` and `plural` props to this component when you render it.
-
-
 ### gettext(message)
 
 The function to translate a string. Accepts original message and returns translation if it exists, otherwise original message.
@@ -223,11 +267,81 @@ Example:
 this.context.nxgettext('day ago', 'days ago', numberOfDays, 'Article publish date');
 ```
 
+## Legacy API
+
+The initial version of this library had been created when React used the legacy version of Context APIs, thus it played a keystone role in the main approach of how to use this library at that time. However, in the late March of 2018, React 16.3 was released and that API became deprecated, so do the main approach used in this library. 
+
+The proper way to use this library is described in the [Usage](#usage) section, this section contains legacy API that will be removed in next versions of the library. We don't encourage you to use it in a new project.
+
+### withGettext(translations, pluralForms, options)
+
+Higher-order function which is exported by default from `react-gettext` package. It accepts two arguments and returns function to create higher-order component.
+
+- **translations**: a hash object or a function which returns hash object where keys are original messages and values are translated messages.
+- **pluralForms**: a string to calculate plural form (used by [Gettext PO](http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html?id=l10n/pluralforms)) or a function which accepts a number and calculates a plural form number. Pay attentions that plural forms are zero-based what means to get 1st plural form it should return 0, to get 2nd - 1, and so on.
+- **options**: a hash object with options. Currently supports following options:
+  - **withRef**: an optional boolean flag that determines whether or not to set `ref` property to a wrapped component what will allow you to get wrapped component instance by calling `getWrappedComponent()` function of the HOC. By default: `FALSE`.
+
+Example:
+
+```javascript
+const translations = {
+    'Some text': 'Some translated text',
+    ...
+};
+
+const pluralForms = '(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)'; // 3 plural forms for Russian, Belarusian, Bosnian, Croatian, Serbian, Ukrainian, etc.
+
+const HOC = withGettext(translations, pluralForms)(App);
+```
+
+```javascript
+function getTranslations() {
+    return {
+        'Some text': 'Some translated text',
+        ...
+    };
+}
+
+function getPluralForms(n) {
+    return n > 1 ? 1 : 0;
+}
+
+const HOC = withGettext(getTranslations, getPluralForms)(App);
+```
+
+As an alternative you can pass translations and plural form as properties to higher-order-component, like this:
+
+```javascript
+function getTranslations() {
+    return {
+        'Some text': 'Some translated text',
+        ...
+    };
+}
+
+function getPluralForms(n) {
+    return n > 1 ? 1 : 0;
+}
+
+const HOC = withGettext()(App);
+
+...
+
+ReactDOM.render(<HOC translations={getTranslations} plural={getPluralForms}>...</HOC>, ...);
+```
+
+One more alternative is to not create HOC, but use Textdomain component directly. You can import it using `import { Textdomain } from 'react-gettext'` and use it as a regular component which will provide context functions to translate your messages. Just don't forget to pass `translations` and `plural` props to this component when you render it.
+
 ## Poedit
 
-If you use Poedit app to translate your messages, then you can use `gettext;ngettext:1,2;xgettext:1,2c;nxgettext:1,2,4c` as keywords list to properly parse and extract strings from your javascript files.
+If you want to use Poedit application to translate your messages, then use the following keywords to properly extract static copy from your javascript files:
 
-Here is an example of a **POT** file which you can start with:
+```
+gettext;ngettext:1,2;xgettext:1,2c;nxgettext:1,2,4c
+```
+
+Here is an example of a **POT** file that you can use as a starting point:
 
 ```
 msgid ""
@@ -246,7 +360,8 @@ msgstr ""
 "X-Poedit-SourceCharset: UTF-8\n"
 ```
 
-If you prefer using npm script, please add this to your package.json file. Make sure correct `project path` and  `output` path is set.
+If you prefer using npm scripts, then you can add the following command to your `package.json` file to extract static copy and generate POT file using CLI commands. Make sure, you have correct `project` and  `output` paths.
+
 ```
 "gettext:extract": "find /path/to/project -name \"*.js\" | xargs xgettext --from-code=UTF-8 --language=JavaScript --keyword=gettext --keyword=ngettext:1,2 --keyword=xgettext:1,2c --keyword=nxgettext:1,2,4c --output=/path/to/project/projectname.pot --sort-by-file --package-name=\"My Project Name\" --package-version=\"1.0.0\""
 ```

diff --git a/__tests__/__setup.js b/__tests__/__setup.js
@@ -0,0 +1,4 @@
+import Enzyme from 'enzyme';
+import Adapter from 'enzyme-adapter-react-16';
+
+Enzyme.configure({ adapter: new Adapter() });