i18n-js 4.0.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b2fdace9fca14d471ff34c3b24055d4093d82ce2a1f72f2df06364a98454a31
-  data.tar.gz: 9ea6bd71626357c8fce24c28e991b9edc96f8a3230e55c4d55cf1dec3813c94e
+  metadata.gz: 6dac70b6202710a44a8303deff7206848d702b4cdb3cc926552aec41114ff745
+  data.tar.gz: 2631494d675d0d8459ab5450bb634fee6c305dd6c01d32bb03d647ac2a657d9e
 SHA512:
-  metadata.gz: 2c8da0348d02f04d805a013dadd24beb08fb7de555bfdded51e4e6c7c29ba392978a723b7e95be9d752dda2b35bbe6d6aefe4d4cf9166c1ddca09f003712533f
-  data.tar.gz: 882af1975b1f2e479ad4d8bdcbe812175fae165c80a2f915223e14fc71fb0b3236774254e103754169eab5a3d577e219e10803fd05e14fa3bac82471e4c770e1
+  metadata.gz: 67c7b4a499d4848967461c1d3a798de2d814af972049f6977d7cf4dc5c6781bfc6ecdc1129068f963ba8dc115ebe5c219f078ef00b92204f86c54a114d55aba3
+  data.tar.gz: 329799184d84e27455783a6a4522b9a0cce446ba33ab3d5cfe74e22d08f685736abb4329e2506e1c2d83504d963c777317f8998a838fb3fae8c358f65569c5b5

data/.github/workflows/ruby-tests.yml

@@ -9,12 +9,15 @@ on:
 
 jobs:
   build:
-    name: Tests with Ruby ${{ matrix.ruby }} and ${{ matrix.gemfile }}
+    name:
+      Tests with Ruby ${{ matrix.ruby }}, Node ${{ matrix.node }} and ${{
+      matrix.gemfile }}
     runs-on: "ubuntu-latest"
     strategy:
       fail-fast: false
       matrix:
         ruby: ["2.7", "3.0", "3.1"]
+        node: ["16", "18"]
         gemfile:
           - Gemfile
     if: |
@@ -32,6 +35,23 @@ jobs:
             ${{ runner.os }}-${{ matrix.ruby }}-gems-${{
             hashFiles(matrix.gemfile) }}
 
+      - uses: actions/cache@v3
+        id: npm-cache
+        with:
+          path: vendor/bundle
+          key: >
+            ${{ runner.os }}-${{ matrix.node }}-npm-${{
+            hashFiles('package.json') }}
+
+      - name: Set up Node
+        uses: actions/setup-node@v2-beta
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Install npm dependencies
+        run: |
+          yarn install
+
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -49,4 +69,5 @@ jobs:
         env:
           BUNDLE_GEMFILE: ${{ matrix.gemfile }}
         run: |
+          yarn compile
           bundle exec rake

data/.gitignore

@@ -9,3 +9,5 @@
 /vendor/
 *.log
 *.lock
+/lib/**/*.js
+/test/output

data/.rubocop.yml

@@ -14,3 +14,6 @@ Naming/FileName:
   Exclude:
     - lib/i18n-js.rb
     - lib/guard/i18n-js.rb
+
+Style/PerlBackrefs:
+  Enabled: false

data/CHANGELOG.md

@@ -11,6 +11,35 @@ Prefix your message with one of the following:
 - [Security] in case of vulnerabilities.
 -->
 
-## Jul 29, 2022
+## v4.2.0 - Dec 10, 2022
+
+- [Added] Add `I18nJS::Plugin.after_export(files:, config:)` method, that's
+  called whenever whenever I18nJS finishes exporting files. You can use it to
+  further process files, or generate new files based on the exported files.
+- [Added] Bult-in plugin `I18nJS::ExportFilesPlugin`, which allows exporting
+  files out of the translations file by using a custom template.
+
+## v4.1.0 - Dec 09, 2022
+
+- [Added] Parse configuration files as erb.
+- [Changed] `I18n.listen(run_on_start:)` was added to control if files should be
+  exported during `I18n.listen`'s boot. The default value is `true`.
+- [Added] Now it's possible to transform translations before exporting them
+  using a stable plugin api.
+- [Added] Built-in plugin `I18nJS::EmbedFallbackTranslationsPlugin`, which
+  allows embedding missing translations on exported files.
+- [Deprecated] The `i18n check` has been deprecated. Use
+  `i18n lint:translations` instead.
+- [Added] Use `i18n lint:scripts` to lint JavaScript/TypeScript.
+- [Fixed] Expand paths passed to `I18nJS.listen(locales_dir:)`.
+
+## v4.0.1 - Aug 25, 2022
+
+- [Fixed] Shell out export to avoid handling I18n reloading heuristics.
+- [Changed] `I18nJS.listen` now accepts a directories list to watch.
+- [Changed] `I18nJS.listen` now accepts
+  [listen](https://rubygems.org/gems/listen) options via `:options`.
+
+## v4.0.0 - Jul 29, 2022
 
 - Official release of i18n-js v4.0.0.

data/MIGRATING_FROM_V3_TO_V4.md

@@ -0,0 +1,191 @@
+# Migrating from v3 to v4
+
+I18n-js v4 is a breaking change release and diverges quite a lot from how the
+previous version worked. This guides summarizes the process of upgrading an app
+that uses i18n-js v3 to v4.
+
+## Development
+
+Previously, you could use a middleware to export translations (some people even
+used this in production 😬). In development, you can now use whatever your want,
+because i18n-js doesn't make any assumptions. All you need to do is running
+`i18n export`, either manually or by using something that listens to file
+changes.
+
+If you like watchman, you can use something like this:
+
+```bash
+#!/usr/bin/env bash
+
+root=`pwd`
+
+watchman watch-del "$root"
+watchman watch-project "$root"
+watchman trigger-del "$root" i18n
+
+watchman -j <<-JSON
+[
+  "trigger",
+  "$root",
+  {
+    "name": "i18n",
+    "expression": [
+      "anyof",
+      ["match", "config/locales/**/*.yml", "wholename"],
+      ["match", "config/locales/**/*.po", "wholename"],
+      ["match", "config/i18n.yml", "wholename"]
+    ],
+    "command": ["i18n", "export"]
+  }
+]
+JSON
+
+# If you're running this through Foreman, then uncomment the following lines:
+# while true; do
+#   sleep 1
+# done
+```
+
+You can also use guard. Make sure you have both
+[guard](https://rubygems.org/packages/guard) and
+[guard-compat](https://rubygems.org/packages/guard-compat) installed and use
+Guardfile file with the following contents:
+
+```ruby
+guard(:"i18n-js",
+      run_on_start: true,
+      config_file: "./config/i18n.yml",
+      require_file: "./config/environment.rb") do
+  watch(%r{^config/locales/.+\.(yml|po)$})
+  watch(%r{^config/i18n.yml$})
+  watch("Gemfile")
+end
+```
+
+To run guard, use `guard start -i`.
+
+Finally, you can use [listen](https://rubygems.org/gems/listen). Create the file
+`config/initializers/i18n.rb` with the following content:
+
+```ruby
+Rails.application.config.after_initialize do
+  require "i18n-js/listen"
+  # This will only run in development.
+  I18nJS.listen
+end
+```
+
+> **Warning**:
+>
+> No matter which approach you choose, the idea is that you _precompile_ your
+> translations when going to production. DO NOT RUN any of the above in
+> production.
+
+## Exporting translations
+
+The build process for i18n now relies on an external CLI called `i18n`. All you
+need to do is executing `i18n export` in your build step to generate the json
+files for your translations.
+
+## Using your translations
+
+The JavaScript package is now a separate thing and need to be installed using
+your favorite tooling (e.g. yarn, npm, pnpm, etc).
+
+```console
+$ yarn add i18n-js@latest
+$ npm i --save-dev i18n-js@latest
+```
+
+From now on, the way you load translations and set up I18n-js is totally up to
+you, but means you need to load the json files and attach to the I18n-js
+instance. This is how I do it in a project I'm doing right now (Rails 7 +
+esbuild + TypeScript). First, we need to load the I18n-js configuration from the
+main JavaScript file:
+
+```typescript
+// app/javascript/application.ts
+import { i18n } from "./config/i18n";
+```
+
+Then we need to load our translations and instantiate the I18n-js class.
+
+```typescript
+// app/javascript/config/i18n.ts
+import { I18n } from "i18n-js";
+import translations from "translations.json";
+
+// Fetch user locale from html#lang.
+// This value is being set on `app/views/layouts/application.html.erb` and
+// is inferred from `ACCEPT-LANGUAGE` header.
+const userLocale = document.documentElement.lang;
+
+export const i18n = new I18n();
+i18n.store(translations);
+i18n.defaultLocale = "en";
+i18n.enableFallback = true;
+i18n.locale = userLocale;
+```
+
+The best thing about the above is that it is a pretty straightforward pattern in
+the JavaScript community. It doesn't rely on specific parts from Sprockets (I'm
+not even using it on my projects) or eRb files.
+
+## Ruby on Rails
+
+### Upgrading the configuration file
+
+The configuration file loaded from `config/i18n.yml` has changed. Given the v3
+configuration below
+
+```yaml
+---
+translations:
+  - file: "app/assets/javascripts/date_formats.js"
+    only: "*.date.formats"
+  - file: "app/assets/javascripts/other.js"
+    only: ["*.activerecord", "*.admin.*.title"]
+  - file: "app/assets/javascripts/everything_else.js"
+    except:
+      - "*.activerecord"
+      - "*.admin.*.title"
+      - "*.date.formats"
+```
+
+the equivalent configuration file for v4 would be
+
+```yaml
+---
+translations:
+  - file: "app/assets/javascripts/date_formats.js"
+    patterns:
+      - "*.date.formats"
+  - file: "app/assets/javascripts/other.js"
+    patterns:
+      - "*.activerecord"
+      - "*.admin.*.title"
+  - file: "app/assets/javascripts/everything_else.js"
+    patterns:
+      # Notice the exclamation mark.
+      - "!*.activerecord"
+      - "!*.admin.*.title"
+      - "!*.date.formats"
+```
+
+Other configuration options:
+
+- `export_i18n_js`: removed without an equivalent
+- `fallbacks`: removed without an equivalent
+- `js_available_locales`: removed (on v4 you can use groups, like in
+  `{pt-BR,en}.*`)
+- `namespace`: removed without an equivalent
+- `sort_translation_keys`: removed (on v4 keys will always be sorted)
+- `translations[].prefix`: removed without an equivalent
+- `translations[].pretty_print`: removed (on v4 files will always be exported in
+  a readable format)
+
+### Placeholders
+
+Previously, v3 had the `%{locale}` placeholder, which can be used as part of the
+directory and/or file name. Now, the syntax is just `:locale`. Additionally, you
+can also use `:digest`, which uses a MD5 hex digest of the exported file.