Gem to visualize i18n strings within a rails project
Ruby HTML JavaScript CoffeeScript CSS
Latest commit f6f2563 Sep 8, 2016 @jhilden jhilden committed on GitHub Merge pull request #19 from MrSenko/keep_html
Keep nested HTML tags when removing i18n keys. Fixes #9
Permalink
Failed to load latest commit information.
assets Keep nested HTML tags when removing i18n keys. Fixes #9 Apr 2, 2016
lib bump version Jul 21, 2016
sass
spec/javascripts Keep nested HTML tags when removing i18n keys. Fixes #9 Apr 2, 2016
test Merge pull request #19 from MrSenko/keep_html Sep 8, 2016
.evergreen moving assets out of the `app` folder Feb 26, 2016
.gitignore only serve compiled CSS from the gem, because anything else doesn't r… May 9, 2012
.rvmrc.example
.travis.yml
CHANGELOG.md
Gemfile fixed to rails `4.2.7` at the moment Jul 21, 2016
MIT-LICENSE
README.md
Rakefile fix 1.9.3 stuff and add js tests to travis Feb 19, 2016
config.rb only serve compiled CSS from the gem, because anything else doesn't r… May 9, 2012
i18n_viz.gemspec assets need to be shipped tough ;) Feb 29, 2016

README.md

I18nViz

Build Status

Gem to visualize i18n strings within anay rails/ruby project using the commonly used i18n gem.

Problem:

It is very difficult for non-developers (e.g. translators and product managers) working with i18n Rails apps to make the connection from a string within the app to the correct i18n key to edit the corresponding translation. "I would like to tweak the wording of the subtitle on this page, what string do I need to edit?"

Solution:

My solution is to hack the i18n keys into the frontend, so that the keys can be displayed as nice overlay tooltips on top of their strings right within the app.

If you you use a translation management service, such as http://webtranslateit.com, https://lingohub.com, http://localeapp.com/, you get the additional benefit of clickable links that point you right to the correct string to edit within your translation tool.

Upgrading from < 0.4.x

1.0.0 was basically a whole new approach how i18n hooks into your application, so if you're using a version below 1.0, this is for you:

Remove JS

If you required the i18n_viz javascript somewhere, remove it :)

// = require i18n_viz

Remove CCS

If you required the i18n_viz stylesheet somewhere, remove it :)

/* = require i18n_viz.css */

Remove initializer

Remove the initializer from config/i18n_viz.rb

THEN follow the new installation instructions

Requirements

  • i18n gem
  • jQuery
  • Rails > 3.1+
  • CoffeeScript

However, with just a little bit of manual work, you should be able to get the whole thing to run without Rails and CoffeeScript. Just let me know if you need help.

Installation

1. Install the gem

Add the following line to your Gemfile and run bundle install:

gem 'i18n_viz'

2. Insert the middleware

add do e.g. config/application.rb:

config.middleware.use(I18nViz::Middleware)

if you want to configure an external tool

config.middleware.use(I18nViz::Middleware) do |viz|
  viz.external_tool_url = "https://webtranslateit.com/en/projects/xxx/locales/en..de/strings?utf8=✓&s="
end

if you want to configure CSS overrides

config.middleware.use(I18nViz::Middleware) do |viz|
  viz.css_override = "/* valid CSS text here */"
end

3. Browse to http://localhost:3000?i18n_viz=true

Add the i18n_viz=true parameter to visualize the translatable segments.

Alternatively, a cookie with the name i18n_viz can be set to any value to achieve the same effect.

How it works

The gem works by overwriting the t() and translate() helpers in your rails app to add the key of the i18n string after the actual translated content:

en:
  examples:
    my_string: "My internationalized string"
    foo: "bar"

%span= "#{t("examples.my_string")} : #{t("examples.foo")}"

Will result in

<span>My internationalized string--examples.my_string-- : bar--examples.foo--</span>

The i18n_viz Javascript then parses this and enriches it into:

<span class="i18n-viz" data-i18nKeys="['examples.my_string', 'examples.foo']">My internationalized string : bar</span>

The so enriched elements then get nice little tooltips attached with the i18n keys and possibly links to where they can be found/changed.

Gotchas & Limitations

Works only in the view layer

The keys will currently only work for strings that are translated in the view layer using the translate() and t() i18n view helpers. If you translate a string the model layer using I18n.translate method directly (e.g. in ActiveRecord validations) the keys are not displayed in the frontend.

Disable i18n_viz if you require certain strings to remain untouched

For certain special strings within your app, the added --key-- could potentially break your custom logic. For those cases you need to call the t() method the additional i18n_viz: false parameter.

Example cases include:

Iterating overy keys

de:
  types:
    foo: "Foo"
    bar: "Bar"

- t("types").each do |key, string|
    .. do something wit the key ..

JS data-attributes

de:
  date:
    js_format: "dd.mm.yyyy"


%body{:"data-date-format" => t("date.js_format")}

Will result in this broken output:

<body data-date-format="dd.mm.yyyy--date.js_format--">

Thanks

Big thanks to my employer Railslove for supporting my open source work and to everybody who helped me.

License

This project is under MIT-LICENSE.