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