Update translations documentation

docs/README.md

@@ -50,7 +50,6 @@ Documentation for specific topics can be found in the following files:
 * [Original create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md)
 * [Customization checklist](customization-checklist.md)
 * [Google Maps](google-maps.md)
-* [i18n](i18n.md)
 * [Icons](icons.md)
 
 The application was bootstrapped with a forked version of

docs/i18n.md

@@ -1,18 +0,0 @@
-# i18n
-
-The application supports having a single language for the UI. By default the language is English.
-
-We are using the [react-intl](https://github.com/yahoo/react-intl) package to translate UI texts and
-to format dates, numbers, money values, etc.
-
-To change the language, do the following:
-
-1.  Copy the default [src/translations/en.json](../src/translations/en.json) English translation
-    messages file into some other file like `es.json`.
-
-1.  Change the messages in the new messages file to your language.
-
-1.  In [src/config.js](../src/config.js), change the `locale` variable value
-
-1.  In [src/app.js](../src/app.js), change the translation imports to come from the correct
-    `react-intl` locale and the new messages file you created.

docs/translations.md

@@ -0,0 +1,141 @@
+# Translations
+
+The Flex template for web supports having a single language for the UI. By default the language is
+English.
+
+We are using the [React Intl](https://github.com/yahoo/react-intl) library to translate UI texts and
+to format dates, numbers, and money values.
+
+## The translation file
+
+All the text translations can be found in the
+[src/translations/en.json](../src/translations/en.json) file. The translation data is formatted as
+one JSON object with all the translations as properties.
+
+The key - value syntax is as follows:
+
+```
+"<component name>.<translation key>": "<translation>"
+```
+
+For example:
+
+```
+"ManageListingCard.viewListing": "View listing"
+```
+
+The keys are namespaced to the corresponding component. This is aligned with the component driven
+paradigm that the application follows. It might introduce duplication with same translation texts
+occurring multiple times in the translation file but it also emphasizes how all the components are
+independent, how a component can be used anywhere and how modifications to a single component do not affect
+other components.
+
+## Using the translations
+
+React Intl provides multiple ways to access the translation data but the most commonly used are the
+`formatMessage` function and the `FormattedMessage` tag provided by React Intl.
+
+To use the `formatMessage` function, component needs to be wrapped with the `injectIntl` function
+which provides a render prop called `intl`. `intl` then provides all the React Intl translation
+functions, like `formatMessage`:
+
+```js
+import { intlShape, injectIntl } from 'react-intl';
+
+const SomeComponent = props => {
+  const { intl } = props;
+
+  const translation = intl.formatMessage({ id: 'SomeComponent.someKey' });
+
+  // ...
+};
+
+SomeComponent.propTypes = {
+  // from injectIntl
+  intl: intlShape.isRequired,
+};
+
+export default injectIntl(SomeComponent);
+```
+
+As for the `FormattedMessage` it just needs to be imported from `react-intl` and it takes the id
+prop:
+
+```
+<FormattedMessage id="SomeCompoennt.someKey" />
+```
+
+Other functions and componets can be explored in the
+[React Intl documentation](https://github.com/yahoo/react-intl/wiki).
+
+## Formatting
+
+React Intl uses the [FormatJS](https://formatjs.io/) formatters for shaping the translation
+texts based on given arguments. Here are a few examples on how to use FormatJS.
+
+### Arguments
+
+Pass a named argument to the format function/component. For the following translation:
+
+```js
+"EnquiryForm.messageLabel": "Message to {authorDisplayName}",
+```
+
+Pass the author data in the `FormattedMessage` component:
+
+```js
+<FormattedMessage id="EnquiryForm.messageLabel" values={{ authorDisplayName: 'Jane D' }} />
+```
+
+Or the the `formatMessage` function:
+
+```js
+intl.formatMessage({ id: 'EnquiryForm.messageLabel' }, { authorDisplayName: 'Jane D' });
+```
+
+### Pluralization
+
+With pluralization a translation can be formatted to adapt to a number argument.
+
+```js
+"ManageListingsPage.youHaveListings": "You have {count} {count, plural, one {listing} other {listings}}",
+```
+
+This translation takes the `count` argument and uses the `plural`, `one` and `other` keywords to
+format the last word of the translation to be _listing_ or _listings_ based on the `count`. The
+pluralized translation can be used with the `FormattedMessage` component:
+
+```js
+<FormattedMessage id="ManageListingsPage.youHaveListings" values={{ count: 3 }} />
+```
+
+Or with the `formatMessage` function:
+
+```js
+intl.formatMessage({ id: 'ManageListingsPage.youHaveListings' }, { count: 1 });
+```
+
+More formatting examples can be found from the
+[FormatJS message syntax documentation](https://formatjs.io/guides/message-syntax/).
+
+## Texts outside the translation file
+
+The `AboutPage` component is the only one that contains text content that can not be found from the
+`en.json` file. It only has static content and consists of one component so the text content can
+easily be added and maintained in that one file. For instructions on creating static pages like the
+About page, refer to the [Static pages documentation](./static-pages.md).
+
+## Changing the language
+
+For changing the language of the template application:
+
+1.  Copy the default [src/translations/en.json](../src/translations/en.json) English translations
+    file into some other file like `es.json`.
+
+1.  Change the messages in the new translations file to the desired language.
+
+1.  In [src/config.js](../src/config.js), change the `locale` variable value to match the new locale
+    (the name of the new translations file, without the extension).
+
+1.  In [src/app.js](../src/app.js), change the translation imports to point to the correct
+    `react-intl` locale and the new translations file you created.