-
-
Notifications
You must be signed in to change notification settings - Fork 631
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Clean up grammar and markdown in the i18n guide (#1459)
- Loading branch information
Showing
1 changed file
with
71 additions
and
83 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,99 +1,87 @@ | ||
| # I18n | ||
| # Internationalization | ||
|
|
||
| Here's a summary of adding the I18n functionality. | ||
| You can use [Rails internationalization (i18n)](https://guides.rubyonrails.org/i18n.html) in your client code. | ||
|
|
||
| 1. Add `config.i18n_dir` in `config/initializers/react_on_rails.rb` | ||
| 1. Set `config.i18n_dir` in `config/initializers/react_on_rails.rb`: | ||
|
|
||
| React on Rails will generate `translations.json` & `default.json` automatically (see #3) after you configured your `config.i18n_dir` in `config/initializers/react_on_rails.rb`. | ||
| ```ruby | ||
| # Replace the following line by the directory containing your translation.js and default.js files. | ||
| config.i18n_dir = Rails.root.join("PATH_TO", "YOUR_JS_I18N_FOLDER") | ||
| ``` | ||
|
|
||
| ```ruby | ||
| # Replace the following line to the location where you keep translation.js & default.js. | ||
| config.i18n_dir = Rails.root.join("PATH_TO", "YOUR_JS_I18N_FOLDER") | ||
| ``` | ||
| If you do not want to use the YAML files from `Rails.root.join("config", "locales")` and installed gems, you can also set `config.i18n_yml_dir`: | ||
| ```ruby | ||
| # Replace the following line by the location of your client i18n yml files | ||
| # Without this option, all YAML files from Rails.root.join("config", "locales") and installed gems are loaded | ||
| config.i18n_yml_dir = Rails.root.join("PATH_TO", "YOUR_YAML_I18N_FOLDER") | ||
| ``` | ||
|
|
||
| Optionally you can also set `config.i18n_yml_dir` if you do not what to use all the locale files from rails. | ||
| ```ruby | ||
| # Replace the following line to the location where you keep your client i18n yml files | ||
| # By default(without this option), all yaml files from Rails.root.join("config", "locales") and installed gems are loaded | ||
| config.i18n_yml_dir = Rails.root.join("PATH_TO", "YOUR_YAML_I18N_FOLDER") | ||
| ``` | ||
| 2. Add that directory (or just the generated files `translations.json` and `default.json`) to your `.gitignore`. | ||
|
|
||
| `translations.json`: All your locales in json format. | ||
| `default.json`: Default settings in json format. | ||
| 3. The locale files must be generated before `yarn build` using `rake react_on_rails:locale`. | ||
|
|
||
| 2. Add `translations.json` and `default.json` to your `.gitignore`. | ||
| For development, you should adjust your startup scripts (`Procfile`s) so that they run `bundle exec rake react_on_rails:locale` before running any webpack watch process (`yarn run build:development`). | ||
|
|
||
| 3. Javascript locale files must be generated before `yarn build`. | ||
| If you are not using the React on Rails test helper, | ||
| you may need to configure your CI to run `bundle exec rake react_on_rails:locale` before any webpack process as well. | ||
|
|
||
| Once you setup `config.i18n_dir` as in the previous step, you will need to make sure `rake react_on_rails:locale` runs before webpack. | ||
|
|
||
| For development, you should adjust your startup scripts (Procfiles) so that they run **`bundle exec rake react_on_rails:locale`** before running any webpack watch process (`yarn run build:development`). | ||
|
|
||
| You may need to configure your CI to run **`bundle exec rake react_on_rails:locale`** before any webpack process if you are not using the React on Rails test helper. | ||
|
|
||
| Note, if you are try to lint before running tests, and you are depending on the test helper to build your locales, your linting will fail because the translations won't be built yet. | ||
|
|
||
| The fix is either to | ||
| 1) run the rake task to build the translations before running the lint command or | ||
| 2) to run the tests first. | ||
| Note: if you try to lint before running tests, and you depend on the test helper to build your locales, linting will fail because the translations won't be built yet. | ||
| # Generate locales with react-intl support | ||
| The fix is either to | ||
| 1) run the rake task to build the translations before running the lint command or | ||
| 2) to run the tests first. | ||
| By default the locales generated in json format. If you need to generate files in the prior way | ||
| with `react-intl` supported via js files: | ||
| By default, the locales are generated as JSON, but you can also generate them as JavaScript with [`react-intl`](https://formatjs.io/docs/getting-started/installation/) support: | ||
| 1. Specify i18n output format in `react_on_rails.rb`: | ||
| ```rb | ||
| config.i18n_output_format = 'js' | ||
| ``` | ||
| 1. Specify the i18n output format in `config/initializers/react_on_rails.rb`: | ||
| ```rb | ||
| config.i18n_output_format = "js" | ||
| ``` | ||
| 2. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle && yarn install`. | ||
| Versions should be newer than these: | ||
| 2. Add `react-intl` & `intl` to `client/package.json`, and remember to `bundle install && yarn install`. The minimum supported versions are: | ||
| ```js | ||
| "dependencies": { | ||
| ```js | ||
| "dependencies": { | ||
| ... | ||
| "intl": "^1.2.5", | ||
| "react-intl": "^2.1.5", | ||
| ... | ||
| } | ||
| ``` | ||
| 3. In React, you need to initialize `react-intl`, and set its parameters: | ||
| ```js | ||
| ... | ||
| import { addLocaleData } from 'react-intl'; | ||
| import en from 'react-intl/locale-data/en'; | ||
| import de from 'react-intl/locale-data/de'; | ||
| import { translations } from 'path_to/i18n/translations'; | ||
| import { defaultLocale } from 'path_to/i18n/default'; | ||
| ... | ||
| // Initizalize all locales for react-intl. | ||
| addLocaleData([...en, ...de]); | ||
| ... | ||
| // set locale and messages for IntlProvider. | ||
| const locale = method_to_get_current_locale() || defaultLocale; | ||
| const messages = translations[locale]; | ||
| ... | ||
| "intl": "^1.2.5", | ||
| "react-intl": "^2.1.5", | ||
| return ( | ||
| <IntlProvider locale={locale} key={locale} messages={messages}> | ||
| <CommentScreen {...{ actions, data }} /> | ||
| </IntlProvider> | ||
| ) | ||
| ``` | ||
| ```js | ||
| // In your component. | ||
| import { defaultMessages } from 'path_to/i18n/default'; | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| 3. Add `translations.js` and `default.js` to your `.gitignore` and `.eslintignore`. | ||
|
|
||
| 4. In React, you need to initialize `react-intl`, and set parameters for it. | ||
|
|
||
| ```js | ||
| ... | ||
| import { addLocaleData } from 'react-intl'; | ||
| import en from 'react-intl/locale-data/en'; | ||
| import de from 'react-intl/locale-data/de'; | ||
| import { translations } from 'path_to/i18n/translations'; | ||
| import { defaultLocale } from 'path_to/i18n/default'; | ||
| ... | ||
| // Initizalize all locales for react-intl. | ||
| addLocaleData([...en, ...de]); | ||
| ... | ||
| // set locale and messages for IntlProvider. | ||
| const locale = method_to_get_current_locale() || defaultLocale; | ||
| const messages = translations[locale]; | ||
| ... | ||
| return ( | ||
| <IntlProvider locale={locale} key={locale} messages={messages}> | ||
| <CommentScreen {...{ actions, data }} /> | ||
| </IntlProvider> | ||
| ) | ||
| ``` | ||
| ```js | ||
| // In your component. | ||
| import { defaultMessages } from 'path_to/i18n/default'; | ||
| ... | ||
| return ( | ||
| { formatMessage(defaultMessages.yourLocaleKeyInCamelCase) } | ||
| ) | ||
| ``` | ||
|
|
||
| # Notes | ||
| * See why using JSON could be better compare to JS if amount of data is hure [ https://v8.dev/blog/cost-of-javascript-2019#json]( https://v8.dev/blog/cost-of-javascript-2019#json). | ||
| * See [Support for Rails' i18n pluralization #1000](https://github.com/shakacode/react_on_rails/issues/1000) for a discussion of issues around pluralization. | ||
| * *Outdated:* You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and [PR #340](https://github.com/shakacode/react-webpack-rails-tutorial/pull/340), [commmited](https://github.com/shakacode/react-webpack-rails-tutorial/commit/ef369ed9d922aea5116ca7e50208169fd7831389) for a complete example. | ||
| return ( | ||
| { formatMessage(defaultMessages.yourLocaleKeyInCamelCase) } | ||
| ) | ||
| ``` | ||
| # Notes | ||
| * See why using JSON can perform better compared to JS for large amounts of data [https://v8.dev/blog/cost-of-javascript-2019#json](https://v8.dev/blog/cost-of-javascript-2019#json). | ||
| * See [Support for Rails' i18n pluralization #1000](https://github.com/shakacode/react_on_rails/issues/1000) for a discussion of issues around pluralization. | ||
| * *Outdated:* You can refer to [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial) and [PR #340](https://github.com/shakacode/react-webpack-rails-tutorial/pull/340), [commmited](https://github.com/shakacode/react-webpack-rails-tutorial/commit/ef369ed9d922aea5116ca7e50208169fd7831389) for a complete example. |