diff --git a/docs/README.md b/docs/README.md index 40e8de06..5609cee1 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/i18n.md b/docs/i18n.md deleted file mode 100644 index 38f49650..00000000 --- a/docs/i18n.md +++ /dev/null @@ -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. diff --git a/docs/translations.md b/docs/translations.md new file mode 100644 index 00000000..96ac0a94 --- /dev/null +++ b/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: + +``` +".": "" +``` + +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: + +``` + +``` + +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 + +``` + +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 + +``` + +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.