i18n-js 3.8.0 → 3.8.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/FUNDING.yml +3 -0
- data/.github/workflows/tests.yaml +100 -0
- data/CHANGELOG.md +10 -1
- data/README.md +442 -343
- data/i18njs.png +0 -0
- data/lib/i18n/js.rb +13 -8
- data/lib/i18n/js/private/config_store.rb +31 -0
- data/lib/i18n/js/version.rb +1 -1
- data/spec/spec_helper.rb +1 -0
- data/yarn.lock +2 -2
- metadata +7 -4
- data/.travis.yml +0 -39
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6d84f832afa07fc57d3a47e72590f2f4c3bc9839f84957a53936f43f3d65118f
|
4
|
+
data.tar.gz: 12bb23a1f69e681d01cbdc2667b172994bdb55ae3e848b74449b03c0af552fa2
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: d7820635c32a92cb118e2896171366adef9f7b1e55249cbce3b548d2cfbf49757c17d6016f86fcde82c5d43a112df9689604d1c086b78961e94fc4fbe7cad645
|
7
|
+
data.tar.gz: 6ed8844898cc3d6b8c4b7373d0f55863a0d86885548dcf07ed853d50e297050739e9e79ab69770fce1a0bb166196593a8eb3cfa48b61c2dc4c024da21717ebf6
|
data/.github/FUNDING.yml
ADDED
@@ -0,0 +1,100 @@
|
|
1
|
+
name: Tests
|
2
|
+
|
3
|
+
on:
|
4
|
+
pull_request:
|
5
|
+
branches:
|
6
|
+
- main
|
7
|
+
paths-ignore:
|
8
|
+
- 'README.md'
|
9
|
+
push:
|
10
|
+
branches:
|
11
|
+
- main
|
12
|
+
paths-ignore:
|
13
|
+
- 'README.md'
|
14
|
+
|
15
|
+
jobs:
|
16
|
+
ruby_unit_tests:
|
17
|
+
name: Ruby Unit Tests
|
18
|
+
if: "contains(github.event.commits[0].message, '[ci skip]') == false"
|
19
|
+
strategy:
|
20
|
+
fail-fast: false
|
21
|
+
matrix:
|
22
|
+
os:
|
23
|
+
- ubuntu
|
24
|
+
ruby:
|
25
|
+
- 2.4
|
26
|
+
- 2.5
|
27
|
+
- 2.6
|
28
|
+
- 2.7
|
29
|
+
gemfile:
|
30
|
+
- gemfiles/i18n_0_6.gemfile
|
31
|
+
- gemfiles/i18n_0_7.gemfile
|
32
|
+
- gemfiles/i18n_0_8.gemfile
|
33
|
+
- gemfiles/i18n_0_9.gemfile
|
34
|
+
- gemfiles/i18n_1_0.gemfile
|
35
|
+
- gemfiles/i18n_1_1.gemfile
|
36
|
+
- gemfiles/i18n_1_2.gemfile
|
37
|
+
- gemfiles/i18n_1_3.gemfile
|
38
|
+
- gemfiles/i18n_1_4.gemfile
|
39
|
+
- gemfiles/i18n_1_5.gemfile
|
40
|
+
- gemfiles/i18n_1_6.gemfile
|
41
|
+
- gemfiles/i18n_1_7.gemfile
|
42
|
+
- gemfiles/i18n_1_8.gemfile
|
43
|
+
allow_failures:
|
44
|
+
- false
|
45
|
+
include:
|
46
|
+
- os: ubuntu
|
47
|
+
ruby: ruby-head
|
48
|
+
gemfile: gemfiles/i18n_1_8.gemfile
|
49
|
+
allow_failures: true
|
50
|
+
env:
|
51
|
+
BUNDLE_GEMFILE: "${{ matrix.gemfile }}"
|
52
|
+
ALLOW_FAILURES: "${{ matrix.allow_failures }}"
|
53
|
+
runs-on: ${{ matrix.os }}-latest
|
54
|
+
continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
|
55
|
+
steps:
|
56
|
+
- name: Checkout
|
57
|
+
uses: actions/checkout@v2
|
58
|
+
- name: Setup Ruby
|
59
|
+
uses: ruby/setup-ruby@v1
|
60
|
+
with:
|
61
|
+
ruby-version: ${{ matrix.ruby }}
|
62
|
+
bundler-cache: true
|
63
|
+
- name: Test
|
64
|
+
run: bundle exec rake spec:ruby || $ALLOW_FAILURES
|
65
|
+
|
66
|
+
js_unit_tests:
|
67
|
+
name: JS Unit Tests
|
68
|
+
if: "contains(github.event.commits[0].message, '[ci skip]') == false"
|
69
|
+
strategy:
|
70
|
+
fail-fast: false
|
71
|
+
matrix:
|
72
|
+
os:
|
73
|
+
- ubuntu
|
74
|
+
node:
|
75
|
+
- 10
|
76
|
+
- 12
|
77
|
+
- 14
|
78
|
+
runs-on: ${{ matrix.os }}-latest
|
79
|
+
steps:
|
80
|
+
- name: Checkout
|
81
|
+
uses: actions/checkout@v2
|
82
|
+
- name: Setup node
|
83
|
+
uses: actions/setup-node@v1
|
84
|
+
with:
|
85
|
+
node-version: ${{ matrix.node }}
|
86
|
+
- name: Get yarn cache directory path
|
87
|
+
id: yarn-cache-dir-path
|
88
|
+
run: echo "::set-output name=dir::$(yarn cache dir)"
|
89
|
+
- uses: actions/cache@v2
|
90
|
+
id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
|
91
|
+
with:
|
92
|
+
path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
|
93
|
+
key: ${{ runner.os }}-yarn-${{ github.ref }}-${{ github.sha }}
|
94
|
+
restore-keys: |
|
95
|
+
${{ runner.os }}-yarn-${{ github.ref }}-
|
96
|
+
${{ runner.os }}-yarn-
|
97
|
+
- name: Install JS Dependencies
|
98
|
+
run: yarn install
|
99
|
+
- name: Test
|
100
|
+
run: npm test
|
data/CHANGELOG.md
CHANGED
@@ -18,6 +18,14 @@ This project adheres to [Semantic Versioning](http://semver.org/).
|
|
18
18
|
- Nothing
|
19
19
|
|
20
20
|
|
21
|
+
## [3.8.1] - 2021-02-25
|
22
|
+
|
23
|
+
### Fixed
|
24
|
+
|
25
|
+
- [Ruby] Fix performance issue reading config
|
26
|
+
(PR: https://github.com/fnando/i18n-js/pull/593)
|
27
|
+
|
28
|
+
|
21
29
|
## [3.8.0] - 2020-10-15
|
22
30
|
|
23
31
|
### Added
|
@@ -473,7 +481,8 @@ And today is not April Fools' Day
|
|
473
481
|
|
474
482
|
|
475
483
|
|
476
|
-
[Unreleased]: https://github.com/fnando/i18n-js/compare/v3.8.
|
484
|
+
[Unreleased]: https://github.com/fnando/i18n-js/compare/v3.8.1...HEAD
|
485
|
+
[3.8.1]: https://github.com/fnando/i18n-js/compare/v3.8.0...v3.8.1
|
477
486
|
[3.8.0]: https://github.com/fnando/i18n-js/compare/v3.7.1...v3.8.0
|
478
487
|
[3.7.1]: https://github.com/fnando/i18n-js/compare/v3.7.0...v3.7.1
|
479
488
|
[3.7.0]: https://github.com/fnando/i18n-js/compare/v3.6.0...v3.7.0
|
data/README.md
CHANGED
@@ -1,17 +1,22 @@
|
|
1
|
-
|
2
|
-
|
3
|
-
|
4
|
-
|
5
|
-
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
1
|
+
<p align="center">
|
2
|
+
<img width="250" height="58" src="https://github.com/fnando/i18n-js/raw/main/i18njs.png" alt="i18n.js">
|
3
|
+
</p>
|
4
|
+
|
5
|
+
<p align="center">
|
6
|
+
It's a small library to provide the Rails I18n translations on the JavaScript.
|
7
|
+
</p>
|
8
|
+
|
9
|
+
<p align="center">
|
10
|
+
<a href="https://github.com/fnando/i18n-js/actions?query=workflow%3ATests"><img src="https://github.com/fnando/i18n-js/workflows/Tests/badge.svg" alt="Tests"></a>
|
11
|
+
<a href="http://badge.fury.io/rb/i18n-js"><img src="http://img.shields.io/gem/v/i18n-js.svg" alt="Gem Version"></a>
|
12
|
+
<a href="https://www.npmjs.com/package/i18n-js"><img src="https://img.shields.io/npm/v/i18n-js.svg" alt="npm"></a>
|
13
|
+
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
|
14
|
+
<a href="https://travis-ci.org/fnando/i18n-js"><img src="http://img.shields.io/travis/fnando/i18n-js.svg" alt="Build Status"></a>
|
15
|
+
<a href="https://coveralls.io/r/fnando/i18n-js"><img src="http://img.shields.io/coveralls/fnando/i18n-js.svg" alt="Coverage Status"></a>
|
16
|
+
<a href="https://gitter.im/fnando/i18n-js"><img src="https://img.shields.io/badge/gitter-join%20chat-1dce73.svg" alt="Gitter"></a>
|
17
|
+
</p>
|
18
|
+
|
19
|
+
---
|
15
20
|
|
16
21
|
Features:
|
17
22
|
|
@@ -23,8 +28,9 @@ Features:
|
|
23
28
|
- Lots more! :)
|
24
29
|
|
25
30
|
## Version Notice
|
26
|
-
The `master` branch (including this README) is for latest `3.0.0` instead of `2.x`.
|
27
31
|
|
32
|
+
The `main` branch (including this README) is for latest `3.0.0` instead of
|
33
|
+
`2.x`.
|
28
34
|
|
29
35
|
## Usage
|
30
36
|
|
@@ -33,13 +39,15 @@ The `master` branch (including this README) is for latest `3.0.0` instead of `2.
|
|
33
39
|
#### Rails app
|
34
40
|
|
35
41
|
Add the gem to your Gemfile.
|
42
|
+
|
36
43
|
```ruby
|
37
44
|
gem "i18n-js"
|
38
45
|
```
|
39
46
|
|
40
47
|
#### Rails with [webpacker](https://github.com/rails/webpacker)
|
41
48
|
|
42
|
-
If you're using `webpacker`, you may need to add the dependencies to your client
|
49
|
+
If you're using `webpacker`, you may need to add the dependencies to your client
|
50
|
+
with:
|
43
51
|
|
44
52
|
```
|
45
53
|
yarn add i18n-js
|
@@ -47,12 +55,14 @@ yarn add i18n-js
|
|
47
55
|
npm install i18n-js
|
48
56
|
```
|
49
57
|
|
50
|
-
For more details, see
|
58
|
+
For more details, see
|
59
|
+
[this gist](https://gist.github.com/bazzel/ecdff4718962e57c2d5569cf01d332fe).
|
51
60
|
|
52
61
|
#### Rails app with [Asset Pipeline](http://guides.rubyonrails.org/asset_pipeline.html)
|
53
62
|
|
54
|
-
If you're using the
|
55
|
-
then you
|
63
|
+
If you're using the
|
64
|
+
[asset pipeline](http://guides.rubyonrails.org/asset_pipeline.html), then you
|
65
|
+
must add the following line to your `app/assets/javascripts/application.js`.
|
56
66
|
|
57
67
|
```javascript
|
58
68
|
//
|
@@ -68,9 +78,9 @@ then you must add the following line to your `app/assets/javascripts/application
|
|
68
78
|
|
69
79
|
#### Rails app without [Asset Pipeline](http://guides.rubyonrails.org/asset_pipeline.html)
|
70
80
|
|
81
|
+
First, put this in your `application.html` (layout file). Then get the JS files
|
82
|
+
following the instructions below.
|
71
83
|
|
72
|
-
First, put this in your `application.html` (layout file).
|
73
|
-
Then get the JS files following the instructions below.
|
74
84
|
```erb
|
75
85
|
<%# This is just an example, you can put `i18n.js` and `translations.js` anywhere you like %>
|
76
86
|
<%# Unlike the Asset Pipeline example, you need to require both **in order** %>
|
@@ -78,55 +88,66 @@ Then get the JS files following the instructions below.
|
|
78
88
|
<%= javascript_include_tag "translations", skip_pipeline: true %>
|
79
89
|
```
|
80
90
|
|
81
|
-
**There are two ways to get `translations.js` (For Rails app without Asset
|
82
|
-
|
83
|
-
|
84
|
-
|
85
|
-
|
86
|
-
|
87
|
-
|
88
|
-
|
89
|
-
|
90
|
-
|
91
|
-
|
92
|
-
|
91
|
+
**There are two ways to get `translations.js` (For Rails app without Asset
|
92
|
+
Pipeline).**
|
93
|
+
|
94
|
+
1. This `translations.js` file can be automatically generated by the
|
95
|
+
`I18n::JS::Middleware`. Just add `config.middleware.use I18n::JS::Middleware`
|
96
|
+
to your `config/application.rb` file.
|
97
|
+
2. If you can't or prefer not to generate this file, you can move the middleware
|
98
|
+
line to your `config/environments/development.rb` file and run
|
99
|
+
`rake i18n:js:export` before deploying. This will export all translation
|
100
|
+
files, including the custom scopes you may have defined on
|
101
|
+
`config/i18n-js.yml`. If `I18n.available_locales` is set (e.g. in your Rails
|
102
|
+
`config/application.rb` file) then only the specified locales will be
|
103
|
+
exported. Current version of `i18n.js` will also be exported to avoid version
|
104
|
+
mismatching by downloading.
|
93
105
|
|
94
106
|
#### Export Configuration (For translations)
|
95
107
|
|
96
|
-
Exported translation files generated by `I18n::JS::Middleware` or
|
97
|
-
|
98
|
-
|
99
|
-
|
100
|
-
|
108
|
+
Exported translation files generated by `I18n::JS::Middleware` or
|
109
|
+
`rake i18n:js:export` can be customized with config file `config/i18n-js.yml`
|
110
|
+
(use `rails generate i18n:js:config` to create it). You can even get more files
|
111
|
+
generated to different folders and with different translations to best suit your
|
112
|
+
needs. The config file also affects developers using Asset Pipeline to require
|
113
|
+
translations. Except the option `file`, since all translations are required by
|
114
|
+
adding `//= require i18n/translations`.
|
101
115
|
|
102
116
|
Examples:
|
117
|
+
|
103
118
|
```yaml
|
104
119
|
translations:
|
105
|
-
- file:
|
106
|
-
|
107
|
-
- file:
|
108
|
-
|
120
|
+
- file: "public/javascripts/path-to-your-messages-file.js"
|
121
|
+
only: "*.date.formats"
|
122
|
+
- file: "public/javascripts/path-to-your-second-file.js"
|
123
|
+
only: ["*.activerecord", "*.admin.*.title"]
|
109
124
|
```
|
110
125
|
|
111
|
-
If `only` is omitted all the translations will be saved. Also, make sure you add
|
126
|
+
If `only` is omitted all the translations will be saved. Also, make sure you add
|
127
|
+
that initial `*`; it specifies that all languages will be exported. If you want
|
128
|
+
to export only one language, you can do something like this:
|
129
|
+
|
112
130
|
```yaml
|
113
131
|
translations:
|
114
|
-
- file:
|
115
|
-
|
116
|
-
- file:
|
117
|
-
|
132
|
+
- file: "public/javascripts/en.js"
|
133
|
+
only: "en.*"
|
134
|
+
- file: "public/javascripts/pt-BR.js"
|
135
|
+
only: "pt-BR.*"
|
118
136
|
```
|
119
137
|
|
120
|
-
Optionally, you can auto generate a translation file per available locale if you
|
138
|
+
Optionally, you can auto generate a translation file per available locale if you
|
139
|
+
specify the `%{locale}` placeholder.
|
140
|
+
|
121
141
|
```yaml
|
122
142
|
translations:
|
123
|
-
- file: "public/javascripts/i18n/%{locale}.js"
|
124
|
-
|
125
|
-
- file: "public/javascripts/frontend/i18n/%{locale}.js"
|
126
|
-
|
143
|
+
- file: "public/javascripts/i18n/%{locale}.js"
|
144
|
+
only: "*"
|
145
|
+
- file: "public/javascripts/frontend/i18n/%{locale}.js"
|
146
|
+
only: ["*.frontend", "*.users.*"]
|
127
147
|
```
|
128
148
|
|
129
149
|
You can also include ERB in your config file.
|
150
|
+
|
130
151
|
```yaml
|
131
152
|
translations:
|
132
153
|
<% Widgets.each do |widget| %>
|
@@ -135,39 +156,37 @@ translations:
|
|
135
156
|
<% end %>
|
136
157
|
```
|
137
158
|
|
138
|
-
You are able to exclude certain phrases or whole groups of phrases by
|
139
|
-
|
140
|
-
|
141
|
-
|
159
|
+
You are able to exclude certain phrases or whole groups of phrases by specifying
|
160
|
+
the YAML key(s) in the `except` configuration option. The outputted JS
|
161
|
+
translations file (exported or generated by the middleware) will omit any keys
|
162
|
+
listed in `except` configuration param:
|
142
163
|
|
143
164
|
```yaml
|
144
165
|
translations:
|
145
|
-
- except: [
|
166
|
+
- except: ["*.active_admin", "*.ransack", "*.activerecord.errors"]
|
146
167
|
```
|
147
168
|
|
148
|
-
|
149
169
|
#### Export Configuration (For other things)
|
150
170
|
|
151
|
-
- `I18n::JS.config_file_path`
|
152
|
-
|
153
|
-
Default: `config/i18n-js.yml`
|
154
|
-
Behaviour: Try to read the config file from that location
|
171
|
+
- `I18n::JS.config_file_path` Expected Type: `String` Default:
|
172
|
+
`config/i18n-js.yml` Behaviour: Try to read the config file from that location
|
155
173
|
|
156
|
-
- `I18n::JS.export_i18n_js_dir_path`
|
157
|
-
|
158
|
-
|
159
|
-
|
160
|
-
|
174
|
+
- `I18n::JS.export_i18n_js_dir_path` Expected Type: `String` Default:
|
175
|
+
`public/javascripts` Behaviour:
|
176
|
+
|
177
|
+
- Any `String`: considered as a relative path for a folder to `Rails.root` and
|
178
|
+
export `i18n.js` to that folder for `rake i18n:js:export`
|
161
179
|
- Any non-`String` (`nil`, `false`, `:none`, etc): Disable `i18n.js` exporting
|
162
180
|
|
163
|
-
- `I18n::JS.sort_translation_keys`
|
164
|
-
Expected Type: `Boolean`
|
165
|
-
Default: `true`
|
181
|
+
- `I18n::JS.sort_translation_keys` Expected Type: `Boolean` Default: `true`
|
166
182
|
Behaviour:
|
167
|
-
|
183
|
+
|
184
|
+
- Sets whether or not to deep sort all translation keys in order to generate
|
185
|
+
identical output for the same translations
|
168
186
|
- Set to true to ensure identical asset fingerprints for the asset pipeline
|
169
187
|
|
170
|
-
- You may also set `export_i18n_js` and `sort_translation_keys` in your config
|
188
|
+
- You may also set `export_i18n_js` and `sort_translation_keys` in your config
|
189
|
+
file, e.g.:
|
171
190
|
|
172
191
|
```yaml
|
173
192
|
export_i18n_js: false
|
@@ -180,21 +199,24 @@ translations:
|
|
180
199
|
- ...
|
181
200
|
```
|
182
201
|
|
183
|
-
To find more examples on how to use the configuration file please refer to the
|
202
|
+
To find more examples on how to use the configuration file please refer to the
|
203
|
+
tests.
|
184
204
|
|
185
205
|
#### Fallbacks
|
186
206
|
|
187
|
-
If you specify the `fallbacks` option, you will be able to fill missing
|
188
|
-
Default value is `true`.
|
207
|
+
If you specify the `fallbacks` option, you will be able to fill missing
|
208
|
+
translations with those inside fallback locale(s). Default value is `true`.
|
189
209
|
|
190
210
|
Examples:
|
211
|
+
|
191
212
|
```yaml
|
192
213
|
fallbacks: true
|
193
214
|
|
194
215
|
translations:
|
195
|
-
- file: "public/javascripts/i18n/%{locale}.js"
|
196
|
-
|
216
|
+
- file: "public/javascripts/i18n/%{locale}.js"
|
217
|
+
only: "*"
|
197
218
|
```
|
219
|
+
|
198
220
|
This will enable merging fallbacks into each file. (set to `false` to disable).
|
199
221
|
If you use `I18n` with fallbacks, the fallbacks defined there will be used.
|
200
222
|
Otherwise `I18n.default_locale` will be used.
|
@@ -203,9 +225,10 @@ Otherwise `I18n.default_locale` will be used.
|
|
203
225
|
fallbacks: :de
|
204
226
|
|
205
227
|
translations:
|
206
|
-
- file: "public/javascripts/i18n/%{locale}.js"
|
207
|
-
|
228
|
+
- file: "public/javascripts/i18n/%{locale}.js"
|
229
|
+
only: "*"
|
208
230
|
```
|
231
|
+
|
209
232
|
Here, the specified locale `:de` will be used as fallback for all locales.
|
210
233
|
|
211
234
|
```yaml
|
@@ -214,42 +237,49 @@ fallbacks:
|
|
214
237
|
de: "en"
|
215
238
|
|
216
239
|
translations:
|
217
|
-
- file: "public/javascripts/i18n/%{locale}.js"
|
218
|
-
|
240
|
+
- file: "public/javascripts/i18n/%{locale}.js"
|
241
|
+
only: "*"
|
219
242
|
```
|
220
|
-
|
243
|
+
|
244
|
+
Fallbacks defined will be used, if not defined (e.g. `:pl`) `I18n.fallbacks` or
|
245
|
+
`I18n.default_locale` will be used.
|
221
246
|
|
222
247
|
```yaml
|
223
248
|
fallbacks: :default_locale
|
224
249
|
|
225
250
|
translations:
|
226
|
-
- file: "public/javascripts/i18n/%{locale}.js"
|
227
|
-
|
251
|
+
- file: "public/javascripts/i18n/%{locale}.js"
|
252
|
+
only: "*"
|
228
253
|
```
|
229
|
-
|
254
|
+
|
255
|
+
Setting the option to `:default_locale` will enforce the fallback to use the
|
256
|
+
`I18n.default_locale`, ignoring `I18n.fallbacks`.
|
230
257
|
|
231
258
|
Examples:
|
259
|
+
|
232
260
|
```yaml
|
233
261
|
fallbacks: false
|
234
262
|
|
235
263
|
translations:
|
236
|
-
- file: "public/javascripts/i18n/%{locale}.js"
|
237
|
-
|
264
|
+
- file: "public/javascripts/i18n/%{locale}.js"
|
265
|
+
only: "*"
|
238
266
|
```
|
239
|
-
You must disable this feature by setting the option to `false`.
|
240
267
|
|
241
|
-
|
268
|
+
You must disable this feature by setting the option to `false`.
|
242
269
|
|
270
|
+
To find more examples on how to use the configuration file please refer to the
|
271
|
+
tests.
|
243
272
|
|
244
273
|
#### Namespace
|
245
274
|
|
246
|
-
Setting the `namespace` option will change the namespace of the output
|
247
|
-
This can be useful in
|
275
|
+
Setting the `namespace` option will change the namespace of the output
|
276
|
+
Javascript file to something other than `I18n`. This can be useful in
|
277
|
+
no-conflict scenarios. Example:
|
248
278
|
|
249
279
|
```yaml
|
250
280
|
translations:
|
251
|
-
- file: "public/javascripts/i18n/translations.js"
|
252
|
-
|
281
|
+
- file: "public/javascripts/i18n/translations.js"
|
282
|
+
namespace: "MyNamespace"
|
253
283
|
```
|
254
284
|
|
255
285
|
will create:
|
@@ -259,19 +289,20 @@ MyNamespace.translations || (MyNamespace.translations = {});
|
|
259
289
|
MyNamespace.translations["en"] = { ... }
|
260
290
|
```
|
261
291
|
|
262
|
-
|
263
292
|
### Adding prefix & suffix to the translations file(s)
|
264
293
|
|
265
|
-
Setting the `prefix: "import I18n from 'i18n-js';\n"` option will add the line
|
266
|
-
|
267
|
-
|
294
|
+
Setting the `prefix: "import I18n from 'i18n-js';\n"` option will add the line
|
295
|
+
at the beginning of the resultant translation file. This can be useful to use
|
296
|
+
this gem with the [i18n-js](https://www.npmjs.com/package/i18n-js) npm package,
|
297
|
+
which is quite useful to use it with webpack. The user should provide the
|
298
|
+
semi-colon and the newline character if needed.
|
268
299
|
|
269
300
|
For example:
|
270
301
|
|
271
302
|
```yaml
|
272
303
|
translations:
|
273
|
-
- file: "public/javascripts/i18n/translations.js"
|
274
|
-
|
304
|
+
- file: "public/javascripts/i18n/translations.js"
|
305
|
+
prefix: "import I18n from 'i18n-js';\n"
|
275
306
|
```
|
276
307
|
|
277
308
|
will create:
|
@@ -281,47 +312,44 @@ import I18n from 'i18n-js';
|
|
281
312
|
I18n.translations || (I18n.translations = {});
|
282
313
|
```
|
283
314
|
|
284
|
-
|
285
315
|
`suffix` option is added in https://github.com/fnando/i18n-js/pull/561.
|
286
316
|
It's similar to `prefix` so won't explain it in details.
|
287
317
|
|
288
|
-
|
289
318
|
#### Pretty Print
|
290
319
|
|
291
|
-
Set the `pretty_print` option if you would like whitespace and indentation in
|
320
|
+
Set the `pretty_print` option if you would like whitespace and indentation in
|
321
|
+
your output file (default: false)
|
292
322
|
|
293
323
|
```yaml
|
294
324
|
translations:
|
295
|
-
- file: "public/javascripts/i18n/translations.js"
|
296
|
-
|
325
|
+
- file: "public/javascripts/i18n/translations.js"
|
326
|
+
pretty_print: true
|
297
327
|
```
|
298
328
|
|
299
|
-
|
300
329
|
#### Javascript Deep Merge (:js_extend option)
|
301
330
|
|
302
|
-
By default, the output file Javascript will call the `I18n.extend` method to
|
303
|
-
files are deep-merged with any locale data
|
304
|
-
|
331
|
+
By default, the output file Javascript will call the `I18n.extend` method to
|
332
|
+
ensure that newly loaded locale files are deep-merged with any locale data
|
333
|
+
already in memory. To disable this either globally or per-file, set the
|
334
|
+
`js_extend` option to false
|
305
335
|
|
306
336
|
```yaml
|
307
|
-
js_extend: false
|
337
|
+
js_extend: false # this will disable Javascript I18n.extend globally
|
308
338
|
translations:
|
309
|
-
- file: "public/javascripts/i18n/translations.js"
|
310
|
-
|
339
|
+
- file: "public/javascripts/i18n/translations.js"
|
340
|
+
js_extend: false # this will disable Javascript I18n.extend for this file
|
311
341
|
```
|
312
342
|
|
313
|
-
|
314
343
|
#### Vanilla JavaScript
|
315
344
|
|
316
|
-
Just add the `i18n.js` file to your page. You'll have to build the translations
|
317
|
-
by hand or using your favorite programming language. More info below.
|
318
|
-
|
345
|
+
Just add the `i18n.js` file to your page. You'll have to build the translations
|
346
|
+
object by hand or using your favorite programming language. More info below.
|
319
347
|
|
320
348
|
#### Via NPM with webpack and CommonJS
|
321
349
|
|
350
|
+
Add the following line to your package.json dependencies where version is the
|
351
|
+
version you want:
|
322
352
|
|
323
|
-
Add the following line to your package.json dependencies
|
324
|
-
where version is the version you want
|
325
353
|
```javascript
|
326
354
|
"i18n-js": "{version_constraint}"
|
327
355
|
|
@@ -329,17 +357,21 @@ where version is the version you want
|
|
329
357
|
// npm install requires it to be the gzipped tarball, see [npm install](https://www.npmjs.org/doc/cli/npm-install.html)
|
330
358
|
"i18n-js": "https://github.com/fnando/i18n-js/archive/{tag_name_or_branch_name_or_commit_sha}.tar.gz"
|
331
359
|
```
|
360
|
+
|
332
361
|
Run npm install then use via
|
362
|
+
|
333
363
|
```javascript
|
334
364
|
var i18n = require("i18n-js");
|
335
365
|
```
|
336
366
|
|
337
|
-
|
338
367
|
### Setting up
|
339
368
|
|
340
|
-
You **don't** need to set up a thing. The default settings will work just okay.
|
369
|
+
You **don't** need to set up a thing. The default settings will work just okay.
|
370
|
+
But if you want to split translations into several files or specify contexts,
|
371
|
+
you can follow the rest of this setting up section.
|
341
372
|
|
342
373
|
Set your locale is easy as
|
374
|
+
|
343
375
|
```javascript
|
344
376
|
I18n.defaultLocale = "pt-BR";
|
345
377
|
I18n.locale = "pt-BR";
|
@@ -347,9 +379,11 @@ I18n.currentLocale();
|
|
347
379
|
// pt-BR
|
348
380
|
```
|
349
381
|
|
350
|
-
**NOTE:** You can now apply your configuration **before I18n** is loaded like
|
382
|
+
**NOTE:** You can now apply your configuration **before I18n** is loaded like
|
383
|
+
this:
|
384
|
+
|
351
385
|
```javascript
|
352
|
-
I18n = {} // You must define this object in top namespace, which should be `window`
|
386
|
+
I18n = {}; // You must define this object in top namespace, which should be `window`
|
353
387
|
I18n.defaultLocale = "pt-BR";
|
354
388
|
I18n.locale = "pt-BR";
|
355
389
|
|
@@ -359,7 +393,8 @@ I18n.currentLocale();
|
|
359
393
|
// pt-BR
|
360
394
|
```
|
361
395
|
|
362
|
-
In practice, you'll have something like the following in your
|
396
|
+
In practice, you'll have something like the following in your
|
397
|
+
`application.html.erb`:
|
363
398
|
|
364
399
|
```erb
|
365
400
|
<script type="text/javascript">
|
@@ -373,7 +408,7 @@ You can use translate your messages:
|
|
373
408
|
```javascript
|
374
409
|
I18n.t("some.scoped.translation");
|
375
410
|
// or translate with explicit setting of locale
|
376
|
-
I18n.t("some.scoped.translation", {locale: "fr"});
|
411
|
+
I18n.t("some.scoped.translation", { locale: "fr" });
|
377
412
|
```
|
378
413
|
|
379
414
|
You can also interpolate values:
|
@@ -381,36 +416,38 @@ You can also interpolate values:
|
|
381
416
|
```javascript
|
382
417
|
// You need the `translations` object setup first
|
383
418
|
I18n.translations["en"] = {
|
384
|
-
greeting: "Hello %{name}"
|
385
|
-
}
|
419
|
+
greeting: "Hello %{name}",
|
420
|
+
};
|
386
421
|
|
387
|
-
I18n.t("greeting", {name: "John Doe"});
|
422
|
+
I18n.t("greeting", { name: "John Doe" });
|
388
423
|
```
|
424
|
+
|
389
425
|
You can set default values for missing scopes:
|
426
|
+
|
390
427
|
```javascript
|
391
428
|
// simple translation
|
392
|
-
I18n.t("some.missing.scope", {defaultValue: "A default message"});
|
429
|
+
I18n.t("some.missing.scope", { defaultValue: "A default message" });
|
393
430
|
|
394
431
|
// with interpolation
|
395
|
-
I18n.t("noun", {defaultValue: "I'm a {{noun}}", noun: "Mac"});
|
432
|
+
I18n.t("noun", { defaultValue: "I'm a {{noun}}", noun: "Mac" });
|
396
433
|
```
|
397
434
|
|
398
435
|
You can also provide a list of default fallbacks for missing scopes:
|
399
436
|
|
400
437
|
```javascript
|
401
438
|
// As a scope
|
402
|
-
I18n.t("some.missing.scope", {defaults: [{scope: "some.existing.scope"}]});
|
439
|
+
I18n.t("some.missing.scope", { defaults: [{ scope: "some.existing.scope" }] });
|
403
440
|
|
404
441
|
// As a simple translation
|
405
|
-
I18n.t("some.missing.scope", {defaults: [{message: "Some message"}]});
|
442
|
+
I18n.t("some.missing.scope", { defaults: [{ message: "Some message" }] });
|
406
443
|
```
|
407
444
|
|
408
|
-
Default values must be provided as an array of hashes where the key is the
|
409
|
-
|
410
|
-
|
445
|
+
Default values must be provided as an array of hashes where the key is the type
|
446
|
+
of translation desired, a `scope` or a `message`. The translation returned will
|
447
|
+
be either the first scope recognized, or the first message defined.
|
411
448
|
|
412
|
-
The translation will fallback to the `defaultValue` translation if no scope
|
413
|
-
|
449
|
+
The translation will fallback to the `defaultValue` translation if no scope in
|
450
|
+
`defaults` matches and if no default of type `message` is found.
|
414
451
|
|
415
452
|
Translation fallback can be enabled by enabling the `I18n.fallbacks` option:
|
416
453
|
|
@@ -420,9 +457,9 @@ Translation fallback can be enabled by enabling the `I18n.fallbacks` option:
|
|
420
457
|
</script>
|
421
458
|
```
|
422
459
|
|
423
|
-
By default missing translations will first be looked for in less
|
424
|
-
|
425
|
-
|
460
|
+
By default missing translations will first be looked for in less specific
|
461
|
+
versions of the requested locale and if that fails by taking them from your
|
462
|
+
`I18n.defaultLocale`.
|
426
463
|
|
427
464
|
```javascript
|
428
465
|
// if I18n.defaultLocale = "en" and translation doesn't exist
|
@@ -431,24 +468,26 @@ them from your `I18n.defaultLocale`.
|
|
431
468
|
I18n.t("some.missing.scope");
|
432
469
|
```
|
433
470
|
|
434
|
-
Custom fallback rules can also be specified for a particular language. There
|
435
|
-
|
471
|
+
Custom fallback rules can also be specified for a particular language. There are
|
472
|
+
three different ways of doing it so:
|
436
473
|
|
437
474
|
```javascript
|
438
475
|
I18n.locales.no = ["nb", "en"];
|
439
476
|
I18n.locales.no = "nb";
|
440
|
-
I18n.locales.no = function(locale){
|
477
|
+
I18n.locales.no = function (locale) {
|
478
|
+
return ["nb"];
|
479
|
+
};
|
441
480
|
```
|
442
481
|
|
443
482
|
By default a missing translation will be displayed as
|
444
483
|
|
445
484
|
[missing "name of scope" translation]
|
446
485
|
|
447
|
-
While you are developing or if you do not want to provide a translation
|
448
|
-
|
486
|
+
While you are developing or if you do not want to provide a translation in the
|
487
|
+
default language you can set
|
449
488
|
|
450
489
|
```javascript
|
451
|
-
I18n.missingBehaviour=
|
490
|
+
I18n.missingBehaviour = "guess";
|
452
491
|
```
|
453
492
|
|
454
493
|
this will take the last section of your scope and guess the intended value.
|
@@ -458,28 +497,34 @@ Camel case becomes lower cased text and underscores are replaced with space
|
|
458
497
|
|
459
498
|
becomes "what is your favorite Christmas present"
|
460
499
|
|
461
|
-
In order to still detect untranslated strings, you can
|
462
|
-
i18n.missingTranslationPrefix to something like:
|
500
|
+
In order to still detect untranslated strings, you can set
|
501
|
+
`i18n.missingTranslationPrefix` to something like:
|
502
|
+
|
463
503
|
```javascript
|
464
|
-
I18n.missingTranslationPrefix =
|
504
|
+
I18n.missingTranslationPrefix = "EE: ";
|
465
505
|
```
|
466
506
|
|
467
507
|
And result will be:
|
508
|
+
|
468
509
|
```javascript
|
469
|
-
"EE: what is your favorite Christmas present"
|
510
|
+
"EE: what is your favorite Christmas present";
|
511
|
+
|
470
512
|
```
|
471
513
|
|
472
514
|
This will help you doing automated tests against your localisation assets.
|
473
515
|
|
474
516
|
Some people prefer returning `null` for missing translation:
|
517
|
+
|
475
518
|
```javascript
|
476
|
-
I18n.missingTranslation = function () {
|
519
|
+
I18n.missingTranslation = function () {
|
520
|
+
return undefined;
|
521
|
+
};
|
477
522
|
```
|
478
523
|
|
479
524
|
Pluralization is possible as well and by default provides English rules:
|
480
525
|
|
481
526
|
```javascript
|
482
|
-
I18n.t("inbox.counting", {count: 10}); // You have 10 messages
|
527
|
+
I18n.t("inbox.counting", { count: 10 }); // You have 10 messages
|
483
528
|
```
|
484
529
|
|
485
530
|
The sample above expects the following translation:
|
@@ -495,21 +540,34 @@ en:
|
|
495
540
|
|
496
541
|
**NOTE:** Rails I18n recognizes the `zero` option.
|
497
542
|
|
498
|
-
If you need special rules just define them for your language, for example
|
543
|
+
If you need special rules just define them for your language, for example
|
544
|
+
Russian, just add a new pluralizer:
|
499
545
|
|
500
546
|
```javascript
|
501
547
|
I18n.pluralization["ru"] = function (count) {
|
502
|
-
var key =
|
548
|
+
var key =
|
549
|
+
count % 10 == 1 && count % 100 != 11
|
550
|
+
? "one"
|
551
|
+
: [2, 3, 4].indexOf(count % 10) >= 0 &&
|
552
|
+
[12, 13, 14].indexOf(count % 100) < 0
|
553
|
+
? "few"
|
554
|
+
: count % 10 == 0 ||
|
555
|
+
[5, 6, 7, 8, 9].indexOf(count % 10) >= 0 ||
|
556
|
+
[11, 12, 13, 14].indexOf(count % 100) >= 0
|
557
|
+
? "many"
|
558
|
+
: "other";
|
503
559
|
return [key];
|
504
560
|
};
|
505
561
|
```
|
506
562
|
|
507
|
-
You can find all rules on
|
563
|
+
You can find all rules on
|
564
|
+
<https://unicode-org.github.io/cldr-staging/charts/37/supplemental/language_plural_rules.html>.
|
508
565
|
|
509
|
-
If you're using the same scope over and over again, you may use the `scope`
|
566
|
+
If you're using the same scope over and over again, you may use the `scope`
|
567
|
+
option.
|
510
568
|
|
511
569
|
```javascript
|
512
|
-
var options = {scope: "activerecord.attributes.user"};
|
570
|
+
var options = { scope: "activerecord.attributes.user" };
|
513
571
|
|
514
572
|
I18n.t("name", options);
|
515
573
|
I18n.t("email", options);
|
@@ -538,14 +596,13 @@ I18n.l("percentage", 123.45);
|
|
538
596
|
// 123.450%
|
539
597
|
```
|
540
598
|
|
541
|
-
To have more control over number formatting, you can use the
|
542
|
-
`I18n.
|
543
|
-
functions.
|
599
|
+
To have more control over number formatting, you can use the `I18n.toNumber`,
|
600
|
+
`I18n.toPercentage`, `I18n.toCurrency` and `I18n.toHumanSize` functions.
|
544
601
|
|
545
602
|
```javascript
|
546
|
-
I18n.toNumber(1000);
|
547
|
-
I18n.toCurrency(1000);
|
548
|
-
I18n.toPercentage(100);
|
603
|
+
I18n.toNumber(1000); // 1,000.000
|
604
|
+
I18n.toCurrency(1000); // $1,000.00
|
605
|
+
I18n.toPercentage(100); // 100.000%
|
549
606
|
```
|
550
607
|
|
551
608
|
The `toNumber` and `toPercentage` functions accept the following options:
|
@@ -558,9 +615,9 @@ The `toNumber` and `toPercentage` functions accept the following options:
|
|
558
615
|
See some number formatting examples:
|
559
616
|
|
560
617
|
```javascript
|
561
|
-
I18n.toNumber(1000, {precision: 0});
|
562
|
-
I18n.toNumber(1000, {delimiter: ".", separator: ","}); // 1.000,000
|
563
|
-
I18n.toNumber(1000, {delimiter: ".", precision: 0});
|
618
|
+
I18n.toNumber(1000, { precision: 0 }); // 1,000
|
619
|
+
I18n.toNumber(1000, { delimiter: ".", separator: "," }); // 1.000,000
|
620
|
+
I18n.toNumber(1000, { delimiter: ".", precision: 0 }); // 1.000
|
564
621
|
```
|
565
622
|
|
566
623
|
The `toCurrency` function accepts the following options:
|
@@ -576,7 +633,7 @@ The `toCurrency` function accepts the following options:
|
|
576
633
|
You can provide only the options you want to override:
|
577
634
|
|
578
635
|
```javascript
|
579
|
-
I18n.toCurrency(1000, {precision: 0}); // $1,000
|
636
|
+
I18n.toCurrency(1000, { precision: 0 }); // $1,000
|
580
637
|
```
|
581
638
|
|
582
639
|
The `toHumanSize` function accepts the following options:
|
@@ -595,18 +652,17 @@ I18n.toHumanSize(1234); // 1KB
|
|
595
652
|
I18n.toHumanSize(1234 * 1024); // 1MB
|
596
653
|
```
|
597
654
|
|
598
|
-
|
599
655
|
#### Date formatting
|
600
656
|
|
601
657
|
```javascript
|
602
658
|
// accepted formats
|
603
|
-
I18n.l("date.formats.short", "2009-09-18");
|
604
|
-
I18n.l("time.formats.short", "2009-09-18 23:12:43");
|
605
|
-
I18n.l("time.formats.short", "2009-11-09T18:10:34");
|
659
|
+
I18n.l("date.formats.short", "2009-09-18"); // yyyy-mm-dd
|
660
|
+
I18n.l("time.formats.short", "2009-09-18 23:12:43"); // yyyy-mm-dd hh:mm:ss
|
661
|
+
I18n.l("time.formats.short", "2009-11-09T18:10:34"); // JSON format with local Timezone (part of ISO-8601)
|
606
662
|
I18n.l("time.formats.short", "2009-11-09T18:10:34Z"); // JSON format in UTC (part of ISO-8601)
|
607
|
-
I18n.l("date.formats.short", 1251862029000);
|
608
|
-
I18n.l("date.formats.short", "09/18/2009");
|
609
|
-
I18n.l("date.formats.short",
|
663
|
+
I18n.l("date.formats.short", 1251862029000); // Epoch time
|
664
|
+
I18n.l("date.formats.short", "09/18/2009"); // mm/dd/yyyy
|
665
|
+
I18n.l("date.formats.short", new Date()); // Date object
|
610
666
|
```
|
611
667
|
|
612
668
|
You can also add placeholders to the date format:
|
@@ -615,14 +671,16 @@ You can also add placeholders to the date format:
|
|
615
671
|
I18n.translations["en"] = {
|
616
672
|
date: {
|
617
673
|
formats: {
|
618
|
-
ordinal_day: "%B %{day}"
|
619
|
-
}
|
620
|
-
}
|
621
|
-
}
|
622
|
-
|
674
|
+
ordinal_day: "%B %{day}",
|
675
|
+
},
|
676
|
+
},
|
677
|
+
};
|
678
|
+
|
679
|
+
I18n.l("date.formats.ordinal_day", "2009-09-18", { day: "18th" }); // Sep 18th
|
623
680
|
```
|
624
681
|
|
625
|
-
If you prefer, you can use the `I18n.toTime` and `I18n.strftime` functions to
|
682
|
+
If you prefer, you can use the `I18n.toTime` and `I18n.strftime` functions to
|
683
|
+
format dates.
|
626
684
|
|
627
685
|
```javascript
|
628
686
|
var date = new Date();
|
@@ -661,8 +719,10 @@ The accepted formats for `I18n.strftime` are:
|
|
661
719
|
Check out `spec/*.spec.js` files for more examples!
|
662
720
|
|
663
721
|
#### Using pluralization and number formatting together
|
664
|
-
|
665
|
-
|
722
|
+
|
723
|
+
Sometimes you might want to display translation with formatted number, like
|
724
|
+
adding thousand delimiters to displayed number You can do this:
|
725
|
+
|
666
726
|
```json
|
667
727
|
{
|
668
728
|
"en": {
|
@@ -674,153 +734,176 @@ You can do this:
|
|
674
734
|
}
|
675
735
|
}
|
676
736
|
```
|
737
|
+
|
677
738
|
```js
|
678
739
|
var point_in_number = 1000;
|
679
|
-
I18n.t(
|
740
|
+
I18n.t("point", {
|
741
|
+
count: point_in_number,
|
742
|
+
formatted_number: I18n.toNumber(point_in_number),
|
743
|
+
});
|
680
744
|
```
|
681
|
-
Output should be `1,000 points`
|
682
745
|
|
746
|
+
Output should be `1,000 points`
|
683
747
|
|
684
748
|
## Using multiple exported translation files on a page.
|
685
|
-
|
749
|
+
|
750
|
+
This method is useful for very large apps where a single contained
|
751
|
+
translations.js file is not desirable. Examples would be a global translations
|
752
|
+
file and a more specific route translation file.
|
686
753
|
|
687
754
|
### Rails without asset pipeline
|
688
|
-
|
689
|
-
|
690
|
-
|
691
|
-
|
692
|
-
|
693
|
-
|
694
|
-
|
695
|
-
|
696
|
-
|
697
|
-
|
698
|
-
|
699
|
-
|
700
|
-
|
701
|
-
|
702
|
-
|
703
|
-
|
704
|
-
|
705
|
-
|
706
|
-
|
707
|
-
|
708
|
-
|
709
|
-
|
710
|
-
|
711
|
-
|
712
|
-
|
713
|
-
|
714
|
-
|
715
|
-
|
716
|
-
|
717
|
-
|
718
|
-
|
719
|
-
|
720
|
-
|
721
|
-
|
722
|
-
|
723
|
-
|
724
|
-
|
725
|
-
|
726
|
-
|
727
|
-
|
728
|
-
|
729
|
-
|
755
|
+
|
756
|
+
1. Setup your `config/i18n-js.yml` to have multiple files and try to minimize
|
757
|
+
any overlap.
|
758
|
+
|
759
|
+
```yaml
|
760
|
+
sort_translation_keys: true
|
761
|
+
fallbacks: false
|
762
|
+
|
763
|
+
translations:
|
764
|
+
+ file: "app/assets/javascript/nls/welcome.js"
|
765
|
+
only:
|
766
|
+
+ '*.welcome.*'
|
767
|
+
|
768
|
+
+ file: "app/assets/javascript/nls/albums.js"
|
769
|
+
only:
|
770
|
+
+ '*.albums.*'
|
771
|
+
|
772
|
+
+ file: "app/assets/javascript/nls/global.js"
|
773
|
+
only:
|
774
|
+
+ '*'
|
775
|
+
# Exempt any routes specific translations from being
|
776
|
+
# included in the global translation file
|
777
|
+
except:
|
778
|
+
+ '*.welcome.*'
|
779
|
+
+ '*.albums.*'
|
780
|
+
```
|
781
|
+
|
782
|
+
When `rake i18n:js:export` is executed it will create 3 translations files that
|
783
|
+
can be loaded via the `javascript_include_tag`
|
784
|
+
|
785
|
+
2. Add the `javascript_include_tag` to your layout and to any route specific
|
786
|
+
files that will require it.
|
787
|
+
|
788
|
+
```ruby
|
789
|
+
# views/layouts/application.html.erb
|
790
|
+
<%= javascript_include_tag(
|
791
|
+
"i18n"
|
792
|
+
"nls/global"
|
793
|
+
) %>
|
794
|
+
```
|
795
|
+
|
796
|
+
and in the route specific
|
797
|
+
|
798
|
+
```ruby
|
799
|
+
# views/welcome/index.html.erb
|
800
|
+
<%= javascript_include_tag(
|
801
|
+
"nls/welcome"
|
802
|
+
) %>
|
803
|
+
```
|
730
804
|
|
731
805
|
3. Make sure that you add these files to your `config/application.rb`
|
732
806
|
|
733
|
-
|
734
|
-
|
735
|
-
|
736
|
-
|
737
|
-
|
738
|
-
|
807
|
+
```ruby
|
808
|
+
config.assets.precompile += %w(
|
809
|
+
i18n
|
810
|
+
nls/*
|
811
|
+
)
|
812
|
+
```
|
739
813
|
|
740
814
|
### Using require.js / r.js
|
741
815
|
|
742
816
|
To use this with require.js we are only going to change a few things from above.
|
743
817
|
|
744
|
-
1. In your `config/i18n-js.yml` we need to add a better location for the i18n to
|
745
|
-
|
746
|
-
|
747
|
-
|
748
|
-
|
749
|
-
|
750
|
-
|
751
|
-
|
752
|
-
|
753
|
-
|
754
|
-
|
755
|
-
|
756
|
-
|
757
|
-
|
758
|
-
|
759
|
-
|
760
|
-
|
761
|
-
|
762
|
-
|
763
|
-
|
764
|
-
|
765
|
-
|
766
|
-
|
767
|
-
|
768
|
-
|
769
|
-
|
770
|
-
|
771
|
-
|
772
|
-
|
773
|
-
|
774
|
-
|
775
|
-
|
776
|
-
|
777
|
-
|
778
|
-
|
779
|
-
|
780
|
-
|
781
|
-
|
782
|
-
|
783
|
-
|
784
|
-
|
785
|
-
|
786
|
-
|
787
|
-
|
788
|
-
|
789
|
-
|
790
|
-
|
791
|
-
|
792
|
-
|
793
|
-
|
794
|
-
|
795
|
-
|
796
|
-
|
797
|
-
|
798
|
-
|
799
|
-
|
800
|
-
|
801
|
-
|
818
|
+
1. In your `config/i18n-js.yml` we need to add a better location for the i18n to
|
819
|
+
be exported to. You want to use this location so that it can be properly
|
820
|
+
precompiled by r.js.
|
821
|
+
|
822
|
+
```yaml
|
823
|
+
export_i18n_js: "app/assets/javascript/nls"
|
824
|
+
```
|
825
|
+
|
826
|
+
2. In your `config/require.yml` we need to add a map, shim all the translations,
|
827
|
+
and include them into the appropriate modules
|
828
|
+
|
829
|
+
```yaml
|
830
|
+
# In your maps add (if you do not have this you will need to add it)
|
831
|
+
map:
|
832
|
+
'*':
|
833
|
+
i18n: 'nls/i18n'
|
834
|
+
|
835
|
+
# In your shims
|
836
|
+
shims:
|
837
|
+
nls/welcome:
|
838
|
+
deps:
|
839
|
+
+ i18n
|
840
|
+
|
841
|
+
nls/global:
|
842
|
+
deps:
|
843
|
+
+ i18n
|
844
|
+
|
845
|
+
# Finally in your modules
|
846
|
+
modules:
|
847
|
+
+ name: 'application'
|
848
|
+
include:
|
849
|
+
+ i18n
|
850
|
+
+ 'nls/global'
|
851
|
+
|
852
|
+
+ name: 'welcome'
|
853
|
+
exclude:
|
854
|
+
+ application
|
855
|
+
include:
|
856
|
+
+ 'nls/welcome'
|
857
|
+
```
|
858
|
+
|
859
|
+
3. When `rake assets:precompile` is executed it will optimize the translations
|
860
|
+
into the correct modules so they are loaded with their assigned module, and
|
861
|
+
loading them with requirejs is as simple as requiring any other shim.
|
862
|
+
|
863
|
+
```javascript
|
864
|
+
define(["welcome/other_asset", "nls/welcome"], function (otherAsset) {
|
865
|
+
// ...
|
866
|
+
});
|
867
|
+
```
|
868
|
+
|
869
|
+
4. (optional) As an additional configuration we can make a task to be run before
|
870
|
+
the requirejs optimizer. This will allow any automated scripts that run the
|
871
|
+
requirejs optimizer to export the strings before we run r.js.
|
872
|
+
|
873
|
+
```rake
|
874
|
+
# lib/tasks/i18n.rake
|
875
|
+
Rake::Task[:'i18n:js:export'].prerequisites.clear
|
876
|
+
task :'i18n:js:export' => :'i18n:js:before_export'
|
877
|
+
task :'requirejs:precompile:external' => :'i18n:js:export'
|
878
|
+
|
879
|
+
namespace :i18n do
|
880
|
+
namespace :js do
|
881
|
+
task :before_export => :'assets:environment' do
|
882
|
+
I18n.load_path += Dir[Rails.root.join('config', 'locales', '*.{yml,rb}')]
|
883
|
+
I18n.backend.load_translations
|
802
884
|
end
|
803
885
|
end
|
804
|
-
|
886
|
+
end
|
887
|
+
```
|
805
888
|
|
806
889
|
## Using I18n.js with other languages (Python, PHP, ...)
|
807
890
|
|
808
|
-
The JavaScript library is language agnostic; so you can use it with PHP, Python,
|
809
|
-
The only requirement is that you need to set the
|
891
|
+
The JavaScript library is language agnostic; so you can use it with PHP, Python,
|
892
|
+
[your favorite language here]. The only requirement is that you need to set the
|
893
|
+
`translations` attribute like following:
|
810
894
|
|
811
895
|
```javascript
|
812
896
|
I18n.translations = {};
|
813
897
|
|
814
898
|
I18n.translations["en"] = {
|
815
|
-
message: "Some special message for you"
|
816
|
-
}
|
899
|
+
message: "Some special message for you",
|
900
|
+
};
|
817
901
|
|
818
902
|
I18n.translations["pt-BR"] = {
|
819
|
-
message: "Uma mensagem especial para você"
|
820
|
-
}
|
903
|
+
message: "Uma mensagem especial para você",
|
904
|
+
};
|
821
905
|
```
|
822
906
|
|
823
|
-
|
824
907
|
## Known Issues
|
825
908
|
|
826
909
|
### Missing translations in precompiled file(s) after adding any new locale file
|
@@ -828,66 +911,80 @@ I18n.translations["pt-BR"] = {
|
|
828
911
|
Due to the design of `sprockets`:
|
829
912
|
|
830
913
|
- `depend_on` only takes file paths, not directory paths
|
831
|
-
- registered `preprocessors` are only run when the fingerprint of any asset
|
914
|
+
- registered `preprocessors` are only run when the fingerprint of any asset
|
915
|
+
file, including `.erb` files, is changed
|
916
|
+
|
917
|
+
This means that new locale files will not be detected, and so they will not
|
918
|
+
trigger a i18n-js refresh. There are a few approaches to work around this:
|
832
919
|
|
833
|
-
|
920
|
+
1. You can force i18n-js to update its translations by completely clearing the
|
921
|
+
assets cache. Use one of the following:
|
834
922
|
|
835
|
-
1. You can force i18n-js to update its translations by completely clearing the assets cache. Use one of the following:
|
836
|
-
|
837
923
|
```bash
|
838
924
|
$ rake assets:clobber
|
839
925
|
# Or, with older versions of Rails:
|
840
926
|
$ rake tmp:cache:clear
|
841
927
|
```
|
842
928
|
|
843
|
-
These commands will remove
|
929
|
+
These commands will remove _all_ fingerprinted assets, and you will have to
|
930
|
+
recompile them with
|
844
931
|
|
845
932
|
```bash
|
846
933
|
$ rake assets:precompile
|
847
934
|
```
|
848
935
|
|
849
|
-
or similar commands. If you are precompiling assets on the target machine(s),
|
936
|
+
or similar commands. If you are precompiling assets on the target machine(s),
|
937
|
+
cached pages may be broken by this, so they will need to be refreshed.
|
850
938
|
|
851
939
|
2. You can change something in a different locale file.
|
852
940
|
|
853
941
|
3. Finally, you can change `config.assets.version`.
|
854
942
|
|
855
|
-
**Note:** See issue [#213](https://github.com/fnando/i18n-js/issues/213) for
|
943
|
+
**Note:** See issue [#213](https://github.com/fnando/i18n-js/issues/213) for
|
944
|
+
more details and discussion of this issue.
|
856
945
|
|
857
946
|
### Translations in JS are not updated when Sprockets not loaded before this gem
|
858
947
|
|
859
|
-
The "rails engine" declaration will try to detect existence of "sprockets"
|
860
|
-
If sprockets is loaded after this gem, the
|
861
|
-
making JS translations file cache to depend on content of
|
862
|
-
So ensure sprockets is loaded before this gem
|
948
|
+
The "rails engine" declaration will try to detect existence of "sprockets"
|
949
|
+
before adding the initailizer If sprockets is loaded after this gem, the
|
950
|
+
preprocessor for making JS translations file cache to depend on content of
|
951
|
+
locale files will not be hooked. So ensure sprockets is loaded before this gem
|
952
|
+
by moving the entry of sprockets in the Gemfile or adding "require" statements
|
953
|
+
for sprockets somewhere.
|
863
954
|
|
864
|
-
**Note:** See issue [#404](https://github.com/fnando/i18n-js/issues/404) for
|
955
|
+
**Note:** See issue [#404](https://github.com/fnando/i18n-js/issues/404) for
|
956
|
+
more details and discussion of this issue.
|
865
957
|
|
866
958
|
### JS `I18n.toCurrency` & `I18n.toNumber` cannot handle large integers
|
867
959
|
|
868
|
-
The above methods use `toFixed` and it only supports 53 bit integers.
|
869
|
-
|
960
|
+
The above methods use `toFixed` and it only supports 53 bit integers. Ref:
|
961
|
+
http://2ality.com/2012/07/large-integers.html
|
870
962
|
|
871
|
-
Feel free to find & discuss possible solution(s) at issue
|
963
|
+
Feel free to find & discuss possible solution(s) at issue
|
964
|
+
[#511](https://github.com/fnando/i18n-js/issues/511)
|
872
965
|
|
873
966
|
### Only works with `Simple` backend
|
874
967
|
|
875
|
-
If you set `I18n.backend` to something other than the default `Simple` backend,
|
968
|
+
If you set `I18n.backend` to something other than the default `Simple` backend,
|
969
|
+
you will likely get an exception like this:
|
876
970
|
|
877
971
|
```
|
878
972
|
Undefined method 'initialized?' for <your backend class>
|
879
973
|
```
|
880
974
|
|
881
|
-
For now, i18n-js is only compatible with the `Simple` backend.
|
882
|
-
|
975
|
+
For now, i18n-js is only compatible with the `Simple` backend. If you need a
|
976
|
+
more sophisticated backend for your rails application, like
|
977
|
+
`I18n::Backend::ActiveRecord`, you can setup i18n-js to get translations from a
|
978
|
+
separate `Simple` backend, by adding the following in an initializer:
|
883
979
|
|
884
980
|
```ruby
|
885
981
|
I18n::JS.backend = I18n.backend
|
886
982
|
I18n.backend = I18n::Backend::Chain.new(<your other backend(s)>, I18n.backend)
|
887
983
|
```
|
888
984
|
|
889
|
-
This will use your backend with the default `Simple` backend as fallback, while
|
890
|
-
|
985
|
+
This will use your backend with the default `Simple` backend as fallback, while
|
986
|
+
i18n-js only sees and uses the simple backend. This means however, that only
|
987
|
+
translations from your static locale files will be present in JavaScript.
|
891
988
|
|
892
989
|
If you do cannot use a `Chain`-Backend for some reason, you can also set
|
893
990
|
|
@@ -896,9 +993,11 @@ I18n::JS.backend = I18n::Backend::Simple.new
|
|
896
993
|
I18n.backend = <something different>
|
897
994
|
```
|
898
995
|
|
899
|
-
However, the automatic reloading of translations in developement will not work
|
900
|
-
This is because Rails calls `I18n.reload!` for each request in
|
901
|
-
|
996
|
+
However, the automatic reloading of translations in developement will not work
|
997
|
+
in this case. This is because Rails calls `I18n.reload!` for each request in
|
998
|
+
development, but `reload!` will not be called on `I18n::JS.backend`, since it is
|
999
|
+
a different object. One option would be to patch `I18n.reload!` in an
|
1000
|
+
initializer:
|
902
1001
|
|
903
1002
|
```ruby
|
904
1003
|
module I18n
|
@@ -909,11 +1008,12 @@ module I18n
|
|
909
1008
|
end
|
910
1009
|
```
|
911
1010
|
|
912
|
-
See issue [#428](https://github.com/fnando/i18n-js/issues/428) for more details
|
1011
|
+
See issue [#428](https://github.com/fnando/i18n-js/issues/428) for more details
|
1012
|
+
and discussion of this issue.
|
913
1013
|
|
914
1014
|
## Maintainer
|
915
1015
|
|
916
|
-
- Nando Vieira - <http://nandovieira.com
|
1016
|
+
- Nando Vieira - <http://nandovieira.com>
|
917
1017
|
|
918
1018
|
## Contributing
|
919
1019
|
|
@@ -921,13 +1021,14 @@ Once you've made your great commits:
|
|
921
1021
|
|
922
1022
|
1. [Fork](http://help.github.com/forking/) I18n.js
|
923
1023
|
2. Create a branch with a clear name
|
924
|
-
3. Make your changes (Please also add/change spec, README and CHANGELOG if
|
1024
|
+
3. Make your changes (Please also add/change spec, README and CHANGELOG if
|
1025
|
+
applicable)
|
925
1026
|
4. Push changes to the created branch
|
926
1027
|
5. [Create an Pull Request](http://github.com/fnando/i18n-js/pulls)
|
927
1028
|
6. That's it!
|
928
1029
|
|
929
|
-
Please respect the indentation rules and code style.
|
930
|
-
And
|
1030
|
+
Please respect the indentation rules and code style. And use 2 spaces, not tabs.
|
1031
|
+
And don't touch the versioning thing.
|
931
1032
|
|
932
1033
|
## Running tests
|
933
1034
|
|
@@ -949,21 +1050,19 @@ You can run both Ruby and JavaScript specs with `rake spec`.
|
|
949
1050
|
|
950
1051
|
(The MIT License)
|
951
1052
|
|
952
|
-
Permission is hereby granted, free of charge, to any person obtaining
|
953
|
-
|
954
|
-
|
955
|
-
|
956
|
-
|
957
|
-
|
958
|
-
|
959
|
-
|
960
|
-
|
961
|
-
|
962
|
-
|
963
|
-
|
964
|
-
|
965
|
-
|
966
|
-
IN
|
967
|
-
|
968
|
-
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
969
|
-
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
1053
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
1054
|
+
this software and associated documentation files (the 'Software'), to deal in
|
1055
|
+
the Software without restriction, including without limitation the rights to
|
1056
|
+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
1057
|
+
the Software, and to permit persons to whom the Software is furnished to do so,
|
1058
|
+
subject to the following conditions:
|
1059
|
+
|
1060
|
+
The above copyright notice and this permission notice shall be included in all
|
1061
|
+
copies or substantial portions of the Software.
|
1062
|
+
|
1063
|
+
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
1064
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
1065
|
+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
1066
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
1067
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
1068
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|