README — Documentation for i18n-js (4.2.2) (2023)

Export i18n translations to JSON.
A perfect fit if you want to export translations to JavaScript.

Oh, you don't use Ruby? No problem! You can still use i18n-js
and thecompanion JavaScript package.

Installation

gem install i18n-js

Or add the following line to your project's Gemfile:

gem "i18n-js"

Usage

About patterns:

Patterns can use * as a wildcard and can appear more than once.
- * will include everything
- *.messages.*
Patterns starting with ! are excluded.
- !*.activerecord.* will exclude all ActiveRecord translations.
You can use groups:
- {pt-BR,en}.js.* will include only pt-BR and en translations, even ifmore languages are available.

Note:
Patterns use glob, so check it out for themost up-to-date documentation about what's available.

The config file:

(Video) VEILLE TECHNO JavaScript Front, Back et FullStack

---translations: - file: app/frontend/locales/en.json patterns: - "*" - "!*.activerecord" - "!*.errors" - "!*.number.nth" - file: app/frontend/locales/:locale.:digest.json patterns: - "*"

The output path can use the following placeholders:

:locale: the language that's being exported.
:digest: the MD5 hex digest of the exported file.

The config file is processed as erb, so you can have dynamic content on it ifyou want. The following example shows how to use groups from a variable.

---<% group = "{en,pt}" %>translations: - file: app/frontend/translations.json patterns: - "<%= group %>.*" - "!<%= group %>.activerecord" - "!<%= group %>.errors" - "!<%= group %>.number.nth"

The Ruby API:

Plugins

Built-in plugins:

`embed_fallback_translations`:

Embed fallback translations inferred from the default locale. This can be usefulin cases where you have multiple large translation files and don't want to loadthe default locale together with the target locale.

To use it, add the following to your configuration file:

embed_fallback_translations: enabled: true

`export_files`:

By default, i18n-js will export only JSON files out of your translations. Thisplugin allows exporting other file formats. To use it, add the following to yourconfiguration file:

export_files: enabled: true files: - template: path/to/template.erb output: "%{dir}/%{base_name}.ts"

You can export multiple files by define more entries.

The output name can use the following placeholders:

(Video) Ruby on Rails | Authentication with Devise.

%{dir}: the directory where the translation file is.
%{name}: file name with extension.
%{base_name}: file name without extension.
%{digest}: MD5 hexdigest from the generated file.

The template file must be a valid eRB template. You can execute arbitrary Rubycode, so be careful. An example of how you can generate a file can be seenbelow:

/* eslint-disable */<%= banner %>import { i18n } from "config/i18n";i18n.store(<%= JSON.pretty_generate(translations) %>);

This template is loading the instance from config/i18n and storing thetranslations that have been loaded. Thebanner(comment: "// ", include_time: true) method is built-in. The generatedfile will look something like this:

/* eslint-disable */// File generated by i18n-js on 2022-12-10 15:37:00 +0000import { i18n } from "config/i18n";i18n.store({ en: { "bunny rabbit adventure": "bunny rabbit adventure", "hello sunshine!": "hello sunshine!", "time for bed!": "time for bed!", }, es: { "bunny rabbit adventure": "conejito conejo aventura", bye: "adios", "time for bed!": "hora de acostarse!", }, pt: { "bunny rabbit adventure": "a aventura da coelhinha", bye: "tchau", "time for bed!": "hora de dormir!", },});

Plugin API

You can transform the exported translations by adding plugins. A plugin mustinherit from I18nJS::Plugin and can have 4 class methods (they're all optionaland will default to a noop implementation). For real examples, see lib/i18n-js/embed_fallback_translations_plugin.rb and lib/i18n-js/export_files_plugin.rb

# frozen_string_literal: truemodule I18nJS class SamplePlugin < I18nJS::Plugin # This method is responsible for transforming the translations. The # translations you'll receive may be already be filtered by other plugins # and by the default filtering itself. If you need to access the original # translations, use `I18nJS.translations`. def transform(translations:) # transform `translations` here… translations end # In case your plugin accepts configuration, this is where you must validate # the configuration, making sure only valid keys and type is provided. # If the configuration contains invalid data, then you must raise an # exception using something like # `raise I18nJS::Schema::InvalidError, error_message`. # # Notice the validation will only happen when the plugin configuration is # set (i.e. the configuration contains your config key). def validate_schema # validate plugin schema here… end # This method must set up the basic plugin configuration, like adding the # config's root key in case your plugin accepts configuration (defined via # the config file). # # If you don't add this key, the linter will prevent non-default keys from # being added to the configuration file. def setup # If you plugin has configuration, uncomment the line below # I18nJS::Schema.root_keys << config_key end # This method is called whenever `I18nJS.call(**kwargs)` finishes exporting # JSON files based on your configuration. # # You can use it to further process exported files, or generate new files # based on the translations that have been exported. def after_export(files:) # process exported files here… end endend

The class I18nJS::Plugin implements some helper methods that you can use:

I18nJS::Plugin#config_key: the configuration key that was inferred out ofyour plugin's class name.
I18nJS::Plugin#config: the plugin configuration.
I18nJS::Plugin#enabled?: whether the plugin is enabled or not based on theplugin's configuration.

To distribute this plugin, you need to create a gem package that matches thepattern i18n-js/*_plugin.rb. You can test whether your plugin will be found byinstalling your gem, opening a iRB session and runningGem.find_files("i18n-js/*_plugin.rb"). If your plugin is not listed, then youneed to double check your gem load path and see why the file is not beingloaded.

Listing missing translations

To list missing and extraneous translations, you can usei18n lint:translations. This command will load your translations similarly tohow i18n export does, but will output the list of keys that don't have amatching translation against the default locale. Here's an example:

$ i18n lint:translations=> Config file: "./config/i18n.yml"=> Require file: "./config/environment.rb"=> Check "./config/i18n.yml" for ignored keys.=> en: 232 translations=> pt-BR: 5 missing, 1 extraneous, 1 ignored - pt-BR.actors.github.metrics (missing) - pt-BR.actors.github.metrics_hint (missing) - pt-BR.actors.github.repo_metrics (missing) - pt-BR.actors.github.repository (missing) - pt-BR.actors.github.user_metrics (missing) - pt-BR.github.repository (extraneous)

This command will exist with status 1 whenever there are missing translations.This way you can use it as a CI linting.

You can ignore keys by adding a list to the config file:

---translations: - file: app/frontend/locales/en.json patterns: - "*" - "!*.activerecord" - "!*.errors" - "!*.number.nth" - file: app/frontend/locales/:locale.:digest.json patterns: - "*"lint_translations: ignore: - en.mailer.login.subject - en.mailer.login.body

Note:
In order to avoid mistakenly ignoring keys, this configuration option onlyaccepts the full translation scope, rather than accepting a pattern likept.ignored.scope.*.
(Video) Les nouveautés d'Angular 12 en français

Linting your JavaScript/TypeScript files

To lint your script files and check for missing translations (which can signalthat you're either using wrong scopes or forgot to add the translation), usei18n lint:scripts. This command will parse your JavaScript/TypeScript filesand extract all scopes being used. This command requires a Node.js runtime. Youcan either specify one via --node-path, or let the plugin infer a binary fromyour $PATH.

The comparison will be made against the export JSON files, which means it'llconsider transformations performed by plugins (e.g. the output files may beaffected by embed_fallback_translations plugin).

The translations that will be extract must be called as one of the followingways:

i18n.t(scope, options)
i18n.translate(scope, options)
t(scope, options)

Notice that only literal strings can be used, as in i18n.t("message"). Ifyou're using dynamic scoping through variables (e.g.const scope = "message"; i18n.t(scope)), they will be skipped.

$ i18n lint:scripts=> Config file: "./config/i18n.yml"=> Require file: "./config/environment.rb"=> Node: "/Users/fnando/.asdf/shims/node"=> Available locales: [:en, :es, :pt]=> Patterns: ["!(node_modules)/**/*.js", "!(node_modules)/**/*.ts", "!(node_modules)/**/*.jsx", "!(node_modules)/**/*.tsx"]=> 9 translations, 11 missing, 4 ignored - test/scripts/lint/file.js:1:1: en.js.missing - test/scripts/lint/file.js:1:1: es.js.missing - test/scripts/lint/file.js:1:1: pt.js.missing - test/scripts/lint/file.js:2:8: en.base.js.missing - test/scripts/lint/file.js:2:8: es.base.js.missing - test/scripts/lint/file.js:2:8: pt.base.js.missing - test/scripts/lint/file.js:4:8: en.js.missing - test/scripts/lint/file.js:4:8: es.js.missing - test/scripts/lint/file.js:4:8: pt.js.missing - test/scripts/lint/file.js:6:1: en.another_ignore_scope - test/scripts/lint/file.js:6:1: es.another_ignore_scope

This command will list all locales and their missing translations. Avoid listinga particular translation, you can set lint.ignore on your config file.

---translations: - file: app/frontend/translations.json patterns: - "*"lint_scripts: ignore: - ignore_scope # will ignore this scope on all languages - pt.another_ignore_scope # will ignore this scope only on `pt`

You can also set the patterns that will be looked up. By default, it scans allJavaScript and TypeScript files that don't live on node_modules.

---translations: - file: app/frontend/translations.json patterns: - "*"lint: patterns: - "app/assets/**/*.ts"

Automatically export translations

Using watchman

Create a script at bin/i18n-watch.

#!/usr/bin/env bashroot=`pwd`watchman watch-del "$root"watchman watch-project "$root"watchman trigger-del "$root" i18nwatchman -j <<-JSON[ "trigger", "$root", { "name": "i18n", "expression": [ "anyof", ["match", "config/locales/**/*.yml", "wholename"], ["match", "config/i18n.yml", "wholename"] ], "command": ["i18n", "export"] }]JSON# If you're running this through Foreman,# the uncomment the following lines:# while true; do# sleep 1# done

Make it executable with chmod +x bin/i18n-watch. To watch for changes, run./bin/i18n-watch. If you're using Foreman, make sure you uncommented the linesthat keep the process running (while..), and add something like the followingline to your Procfile:

i18n: ./bin/i18n-watch

Using guard

Install guard andguard-compat. Then create a Guardfilewith the following configuration:

guard(:"i18n-js", run_on_start: true, config_file: "./config/i18n.yml", require_file: "./config/environment.rb") do watch(%r{^(app|config)/locales/.+\.(yml|po)$}) watch(%r{^config/i18n.yml$}) watch("Gemfile")end

If your files are located in a different path, remember to configure file pathsaccordingly.

(Video) Upgrading to React Native 0.67 - React Native Live with Jamon

Now you can run guard start -i.

Using listen

Create a file under config/initializers/i18n.rb with the following content:

Rails.application.config.after_initialize do require "i18n-js/listen" I18nJS.listenend

The code above will watch for changes based on config/i18n.yml andconfig/locales. You can customize these options:

config_file - i18n-js configuration file
locales_dir - one or multiple directories to watch for locales changes
options - passed directly tolisten
run_on_start - export files on start. Defaults to true. When disabled,files will be exported only when there are file changes.

Example:

I18nJS.listen( config_file: "config/i18n.yml", locales_dir: ["config/locales", "app/views"], options: {only: %r{.yml$}}, run_on_start: false)

Integrating with your frontend

You're done exporting files, now what? Well, go toi18n to discover how to use the NPM packagethat loads all the exported translation.

FAQ

I'm running v3. Is there a migration plan?

There's a documentoutlining some of the things you need to do to migrate from v3 to v4. It may notbe as complete as we'd like it to be, so let us know if you face any issuesduring the migration is not outline is that document.

How can I export translations without having a database around?

Some people may have a build process using something like Docker that don'tnecessarily have a database available. In this case, you may define your ownloading file by using something likei18n export --require ./config/i18n_export.rb, where i18n_export.rb may looklike this:

# frozen_string_literal: truerequire "bundler/setup"require "rails"require "active_support/railtie"require "action_view/railtie"I18n.load_path += Dir["./config/locales/**/*.yml"]

Note:
You may not need to load ActiveSupport and ActionView lines, or even may needto add additional requires for other libs. With this approach you have fullcontrol on what's going to be loaded.

Maintainer

Nando Vieira

Contributors

https://github.com/fnando/i18n-js/contributors

Contributing

For more details about how to contribute, please readhttps://github.com/fnando/i18n-js/blob/main/CONTRIBUTING.md.

(Video) AWS에 서비스 배포하기

License

The gem is available as open source under the terms of theMIT License. A copy of the license can befound at https://github.com/fnando/i18n-js/blob/main/LICENSE.md.

Code of Conduct

Everyone interacting in the i18n-js project's codebases, issue trackers, chatrooms and mailing lists is expected to follow thecode of conduct.