Merge pull request #828 from opentripplanner/yaml-sort

Perform yaml-sort on i18n pre-commit

Author: binh-dam-ibigroup

Diff for: README.md

@@ -39,11 +39,62 @@ env JS_CONFIG=my-custom-js.js CUSTOM_CSS=my-custom-css.css yarn build
 OTP-react-redux uses `react-intl` from the [`formatjs`](https://github.com/formatjs/formatjs) library for internationalization.
 Both `react-intl` and `formatjs` take advantage of native internationalization features provided by web browsers.
 
+### `i18n` Folder
+
 Language-specific content is located in YML files under the `i18n` folder
 (e.g. `en-US.yml` for American English, `fr.yml` for generic French, etc.).
 
-Most textual content can also be customized using the `language` section of `config.yml`,
-whether for all languages at once or for each supported individual language.
+In each of these files:
+  - Messages are organized in various categories and sub-categories.
+  - A component or JS module can use messages from one or more categories.
+  - In the code, messages are retrieved using an ID that is simply the path to the message.
+    Use the dot '.' to separate categories and sub-categories in the path.
+    For instance, for the message defined in YML below:
+    ```yaml
+    common
+      modes
+        subway: Metro
+    ```
+    then use the snippet below with the corresponding message id:
+    ```jsx
+    <FormattedMessage id="common.modes.subway" /> // renders "Metro".
+    ```
+
+In these YML files, it is important that message ids in the code be consistent with
+the categories in this file. Below are some general guidelines:
+  - For starters, there are an `actions`, `common`, `components`, and `config`
+    categories. Additional categories may be added as needed.
+  - Each sub-category under `components` denotes a React component and
+    should contain messages that are used only by that component (e.g. button captions).
+  - In contrast, some strings are common to multiple components,
+    so it makes sense to group them by theme (e.g. accessModes) under the `common` category.
+
+Note: Do not put comments in the YML files! They will be removed by `yaml-sort`.
+Instead, comments for other developers should be placed in the corresponding js/jsx/ts/tsx file.
+Comments for translators should be entered into Weblate (see [Contributing Translations](#contributing-translations))
+
+### Internationalizable content in the configuration file
+
+Most textual content from the `i18n` folder can also be customized on a per-configuration basis
+using the `language` section of `config.yml`, whether for all languages at once,
+or for each supported individual language.
+
+### Using internationalizable content in the code
+
+Use message id **literals** (no variables or other dynamic content) with either
+```jsx
+<FormattedMessage id="..." />
+```
+or
+```js
+intl.formatMessage({ id: ... })
+```
+
+The reason for passing **literals** to `FormattedMessage` and `intl.formatMessage` is that we have a checker script `yarn check:i18n` that is based on the `formatJS` CLI and that detects unused messages in the code and exports translation tables.
+Passing variables or dynamic content will cause the `formatJS` CLI and the checker to ignore the corresponding messages and
+incorrectly claim that a string is unused or missing from a translation file.
+
+One exception to this rule concerns configuration settings where message ids can be constructed dynamically.
 
 ### Contributing translations
 
@@ -62,6 +113,7 @@ OTP-react-redux now uses [Hosted Weblate](https://www.weblate.org) to manage tra
 Translations from the community are welcome and very much appreciated,
 please see instructions at https://hosted.weblate.org/projects/otp-react-redux/.
 Community input from Weblate will appear as pull requests with changes to files in the `i18n` folder for our review.
+(Contributions may be edited or rejected to remain in line with long-term project goals.)
 
 If changes to a specific language file is needed but not enabled in Weblate, please open an issue or a pull request with the changes needed.