Merge branch 'feature/enhance-translate-function'

Author: ryanjohnson

README.md

@@ -131,7 +131,7 @@ const mapStateToProps = state => ({
 export default connect(mapStateToProps)(Greeting);
 ```
 
-For components not already using `connect` instead use [localize](#localizecomponent). This will automatically connect your component with the `translate` function and `currentLanguage` prop. 
+For components not already using `connect` instead use [localize](#localizecomponent-slice). This will automatically connect your component with the `translate` function and `currentLanguage` prop. 
 
 ```javascript
 import { localize } from 'react-localize-redux';
@@ -204,6 +204,38 @@ Then pass in the data you want to swap in for placeholders to the `translate` fu
 <h1>{ translate('info.greeting') }</h1>
 ```
 
+### Pass multiple translations to child components
+
+A parent component that has added the `translate` function by using [getTranslate](#gettranslatestate) or [localize](#localizecomponent-slice) can easily pass multiple translations down to it's child components. Just pass the `translate` function an array of translation keys instead of a single key. 
+
+```json
+{
+  "heading": ["Heading", "Heading French"],
+  "article": {
+    "title": ["Title", "Title French"],
+    "author": ["By ${ name }", "By French ${ name }"],
+    "desc": ["Description", "Description French"]
+  }
+}
+```
+
+```javascript
+const Article = props => (
+  <div>
+    <h2>{ props['article.title'] }</h2>
+    <h3>{ props['article.author'] }</h3>
+    <p>{ props['article.desc'] }</p>
+  </div>
+);
+
+const Page = ({ translate }) => (
+  <div>
+    <h1>{ translate('heading') }</h1>
+    <Article { ...translate(['article.title', 'article.author', 'article.desc'], { name: 'Ted' }) } />
+  </div>
+);
+```
+
 ### Load translation data on demand
 
 If you have a larger app you may want to break your translation data up into multiple files, or maybe your translation data is being loaded from a service. Either way you can call [addTranslation](#addtranslationdata) for each new translation file/service, and the new translation data will be merged with any existing data.
@@ -216,12 +248,12 @@ Also If you are using a tool like [webpack](https://webpack.js.org) for bundling
 
 A selector that takes the localeReducer slice of your `state` and returns the translate function. This function will have access to any and all translations that were added with [addTranslation](#addtranslationdata).
 
-returns `(key, data) => LocalizedElement`
+returns `(key | key[], data) => LocalizedElement | { [key: string]: LocalizedElement }`
 
-* `key: string` = The key for the transaltion string e.g. 'greeting'
+* `key: string|array` = A translation key or an array of translation keys.
 * `data: object` = Pass data to your [dynamic translation](#add-dynamic-content-to-translations) string.
 
-#### Usage: 
+#### Usage (single translation): 
 
 ```javascript
 const Greeting = ({ translate }) => <h1>{ translate('greeting', { name: 'Testy McTest' }) }</h1>
@@ -230,6 +262,10 @@ const mapStateToProps = state => ({ translate: getTranslate(state.locale) });
 export default connect(mapStateToProps)(Greeting);
 ```
 
+#### Usage (multiple translations): 
+
+See [Pass multiple translations to child components](#pass-multiple-translations-to-child-components).
+
 ### `getActiveLanguage(state)`
 
 A selector that takes the localeReducer slice of your `state` and returns the currently active language object.
@@ -266,7 +302,32 @@ const mapStateToProps = state => ({ languages: getLanguages(state.locale) });
 export default connect(mapStateToProps)(Greeting);
 ```
 
-### `localize(Component, slice)`
+### `getLanguages(state)`
+
+A selector that takes your redux `state` and returns the languages you set.
+
+returns `[{ code: 'en', active: true }, { code: 'fr', active: false }]`;
+
+#### Usage: 
+
+```javascript
+const LanguageSelector = ({ languages }) => (
+  <ul>
+    { languages.map(language => 
+      <a href={ `/${ language.code }` }>{ language.code }</a>
+    )}
+  </ul>
+)
+
+const mapStateToProps = state => ({ languages: getLanguages(state) });
+export default connect(mapStateToProps)(Greeting);
+```
+
+### `getTranslations(state)`
+
+A selector that takes your redux `state` and returns the raw translation data.
+
+### `localize(Component)`
 
 If you have a Component that is not using `connect` you can wrap it with `localize` to automatically add the `translate` function and `currentLanguage` prop. When using `combineReducers` to add `localeReducer` you must pass the `slice` param to `localize`, where `slice` is the name of the prop you used with `combineReducers` (e.g. locale).
 

src/modules/locale.js

@@ -111,5 +111,18 @@ export const getTranslationsForActiveLanguage = customeEqualSelector(
 
 export const getTranslate = (state) => {
   const translations = getTranslationsForActiveLanguage(state);
-  return (key, data) => getLocalizedElement(key, translations, data);
+  return (value, data) => { 
+    if (typeof value === 'string') {
+      return getLocalizedElement(value, translations, data);
+    } else if (Array.isArray(value)) {
+      return value.reduce((prev, cur) => {
+        return {
+          ...prev,
+          [cur]: getLocalizedElement(cur, translations, data)
+        };
+      }, {});
+    } else {
+      throw new Error('react-localize-redux: invalid key passed to translate.');
+    }
+  }
 };

tests/modules.test.js

@@ -1,38 +1,10 @@
 import * as actions from 'modules/locale';
-import { languages, translations, getActiveLanguage, getTranslationsForActiveLanguage, customeEqualSelector, setLanguages } from 'modules/locale';
+import { shallow } from 'enzyme';
+import { languages, translations, getActiveLanguage, getTranslationsForActiveLanguage, customeEqualSelector, setLanguages, getTranslate } from 'modules/locale';
 import { SET_LANGUAGES, SET_ACTIVE_LANGUAGE, ADD_TRANSLATION } from 'modules/locale';
 
 describe('locale module', () => {
 
-  let mainState = {};
-
-  beforeEach(() => {
-    mainState = {
-      locale: {
-        currentLanguage: 'en',
-        translations: {
-          global: {
-            en: {
-              title: 'Global Title'
-            },
-            fr: {
-              title: 'FR Global Title'
-            }
-          },
-          local: {
-            en: {
-              greeting: 'Greeting'
-            },
-            fr: {
-              greeting: 'FR Greeting'
-            }
-          }
-        }
-      }
-    };
-  });
-
-
   describe('reducer: languages', () => {
     let initialState = [];
 
@@ -226,6 +198,68 @@ describe('locale module', () => {
     });
   });
 
+  describe('getTranslate', () => {
+    let state = {};
+
+    beforeEach(() => {
+      state = {
+        languages: [{ code: 'en', active: false }, { code: 'fr', active: true }],
+        translations: {
+          hi: ['hi-en', 'hi-fr'],
+          bye: ['bye-en', 'bye-fr'],
+          yo: ['yo ${ name }', 'yo-fr ${ name }'],
+          foo: ['foo ${ bar }', 'foo-fr ${ bar }']
+        }
+      };
+    });
+
+    it('should throw an error when invalid key provided to translate function', () => {
+      const translate = getTranslate(state);
+      expect(() => translate(23)).toThrow();
+    });
+
+    it('should return single translated element when valid key provided', () => {
+      const translate = getTranslate(state);
+      const result = translate('hi');
+      const wrapper = shallow(result);
+      expect(wrapper.text()).toBe('hi-fr');
+      expect(wrapper.type()).toBe('span');
+    });
+
+    it('should return an object of translation keys matched with translated element', () => {
+      const translate = getTranslate(state);
+      const result = translate(['hi', 'bye']);
+      
+      Object.keys(result).map((key, index) => {
+        const element = result[key];
+        const wrapper = shallow(element);
+        expect(wrapper.text()).toBe(state.translations[key][1]);
+      });
+    });
+
+    it('should insert dynamic data for single translation', () => {
+      const translate = getTranslate(state);
+      const element = translate('yo', { name: 'ted' });
+      const wrapper = shallow(element);
+      expect(wrapper.text()).toBe('yo-fr ted');
+    });
+
+    it('should insert dynamic data for multiple translations', () => {
+      const translate = getTranslate(state);
+      const result = translate(['yo', 'foo'], { name: 'ted', bar: 'bar' });
+      const results = [
+        'yo-fr ted',
+        'foo-fr bar'
+      ];
+      
+      Object.keys(result).map((key, index) => {
+        const element = result[key];
+        const wrapper = shallow(element);
+        expect(wrapper.text()).toBe(results[index]);
+      });
+    });
+  });
+
   describe('createSelectorCreator', () => {
     let languages = [];
     let activeLanguage = {};