diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ec52296db..2780cfbdf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,7 @@ Have questions about this document or anything not covered here? Feel free to re * [Typechecking with PropTypes](#typechecking-with-proptypes) * [Naming Functions](#naming-functions) * [Default State Initialization](#default-state-initialization) +* [Internationalization](#internationalization) ## Things to know prior to submitting code @@ -214,3 +215,30 @@ mountWithContexts(< { } }); ``` + +## Internationalization + +Internationalization leans on the [lingui](https://github.com/lingui/js-lingui) project. [Official documentation here](https://lingui.js.org/). We use this libary to mark our strings for translation. If you want to see this in action you'll need to take the following steps: + +### Marking strings for translation and replacement in the UI + +The lingui library provides various React helpers for dealing with both marking strings for translation, and replacing strings that have been traslated. For consistency and ease of use, we have consolidated on one pattern for the codebase. To set strings to be translated in the UI: + +- import the withI18n function and wrap the export of your component in it (i.e. `export default withI18n()(Foo)`) +- doing the above gives you access to the i18n object on props. Make sure to put it in the scope of the function that contains strings needed to be translated (i.e. `const { i18n } = this.props;`) +- import the t template tag function from the @lingui/macro package. +- wrap your string using the following format: ```i18n._(t`String to be translated`)``` + +**Note:** Variables that are put inside the t-marked template tag will not be translated. If you have a variable string with text that needs translating, you must wrap it in ```i18n._(t``)``` where it is defined. + +**Note:** We do not use the `I18n` consumer, `i18nMark` function, or `` component lingui gives us access to in this repo. i18nMark does not actually replace the string in the UI (leading to the potential for untranslated bugs), and the other helpers are redundant. Settling on a consistent, single pattern helps us ease the mental overhead of the need to understand the ins and outs of the lingui API. + +You can learn more about the ways lingui and its React helpers at [this link](https://lingui.js.org/tutorials/react-patterns.html). + +### Setting up .po files to give to translation team + +1) `npm run add-locale` to add the language that you want to translate to (we should only have to do this once and the commit to repo afaik). Example: `npm run add-locale en es fr` # Add English, Spanish and French locale +2) `npm run extract-strings` to create .po files for each language specified. The .po files will be placed in src/locales but this is configurable. +3) Open up the .po file for the language you want to test and add some translations. In production we would pass this .po file off to the translation team. +4) Once you've edited your .po file (or we've gotten a .po file back from the translation team) run `npm run compile-strings`. This command takes the .po files and turns them into a minified JSON object and can be seen in the `messages.js` file in each locale directory. These files get loaded at the App root level (see: App.jsx). +5) Change the language in your browser and reload the page. You should see your specified translations in place of English strings. diff --git a/README.md b/README.md index de22f94b42..3b192e3fcb 100644 --- a/README.md +++ b/README.md @@ -27,13 +27,3 @@ To run a single test (in this case the login page test): * `npm test -- __tests__/pages/Login.jsx` **note:** Once the test watcher is up and running you can hit `a` to run all the tests - -## Internationalization - -Internationalization leans on the [lingui](https://github.com/lingui/js-lingui) project. [Official documentation here](https://lingui.js.org/). We use this libary to mark our strings for translation. For common React use cases see [this link](https://lingui.js.org/tutorials/react-patterns.html). If you want to see this in action you'll need to take the following steps: - -1) `npm run add-locale` to add the language that you want to translate to (we should only have to do this once and the commit to repo afaik). Example: `npm run add-locale en es fr` # Add English, Spanish and French locale -2) `npm run extract-strings` to create .po files for each language specified. The .po files will be placed in src/locales but this is configurable. -3) Open up the .po file for the language you want to test and add some translations. In production we would pass this .po file off to the translation team. -4) Once you've edited your .po file (or we've gotten a .po file back from the translation team) run `npm run compile-strings`. This command takes the .po files and turns them into a minified JSON object and can be seen in the `messages.js` file in each locale directory. These files get loaded at the App root level (see: App.jsx). -5) Change the language in your browser and reload the page. You should see your specified translations in place of English strings.