i18n_viz 0.0.2 → 0.3.0

data/README.md

@@ -1,44 +1,94 @@
 # I18nViz
 
-Gem to visualize i18n strings within a rails project.
+[![Build Status](https://secure.travis-ci.org/jhilden/i18n_viz.png?branch=master)](http://travis-ci.org/jhilden/i18n_viz)
+
+Gem to visualize i18n strings within a rails/ruby project.
+
+**Problem**:
+
+It is ver 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 app, such as http://webtranslateit.com, you get the additional benefit of clickable links that point you right to the correct string to edit within the translation tool.
+
+More features (like inline editing) are possible in the future.
+
 
-More description coming soon ...
 
 ## Requirements
 
-i18n_viz.js currentyl depends on jQuery being alread loaded in your app.  Tested with jQuery 1.6.1
+i18n_viz.js currently depends on jQuery being already loaded in your app (Tested with jQuery 1.6.1, but should also work with other versions)
+
+In a Rails 3.1+ application you should simply include `gem 'jquery-rails'` in your Gemfile and your asset pipeline manifest.
+
 
 ## Installation
 
 ##### 1. Install the gem
 
-Add the following line to your Gemfile
+Add the `i18n_viz` to your Gemfile
 
-    gem 'i18n_viz', :git =>'git://github.com/jhilden/i18n_viz.git'
+    gem 'i18n_viz'
 
 And run
 
     bundle install
 
 
-##### 2. Run install generator
+##### 2. Include the assets
+
+I18nVIz is build as a Rails::Engine, which allows it provide its assets directly to the Rails asset pipeline for inclusion in your app.  Therefore, if you have a Rails 3.1+ app and are using the asset pipeline, you can include the I18nViz assets very easily:
+
+Either you add the following line to your asset pipeline manifest file (`app/assets/javascripts/application.js`):
 
-    rails generate i18n_viz:install
+    // = require i18n_viz
 
-This will copy the required assets (i18n_viz.js, i18n_viz.css) to your public directory and create a new initializer in your rails app.
+Or, you turn your manifest file into an `.erb` template (`app/assets/javascripts/application.js.erb`) and this code:
 
+   <% require_asset("i18n_viz")  if I18nViz.enabled? %>
 
-##### 3. Include assets
+This ensures that the asset will only be included if the I18nViz gem is enabled and makes most sense in combination with an initializer (see below) that enables the gem based on the enviornment.
+
+!Gotcha:  You need to leave a blank line between your asset pipeline directives (`require`, `require_tree`, ...) and the erb line above, otherwise it will NOT work!
+    
+For the stylesheet is is very similar, either you you add a simple directive in your manifest (`app/assets/stylesheets/application.js`):
+
+    /* = require i18n_viz.css */
+
+Or you turn it into an `erb` template (`app/assets/stylesheets/application.css.erb`) and add this at the top of the file:
+
+    <% require_asset "i18n_viz"  if I18nViz.enabled? %>
+    
+<!--Or if you are using SASS, something like:
+
+    @import "i18n_viz"-->
+    
+    
+If you are not using Rails 3.1+ and the asset pipeline you will need to compile the Coffeescript to Javascript and copy and include the assets in the right places.  If there should be demand for it I might provide some more comfortable way of doing this.
 
-For example like this in your app's layout:
 
-    - if display_i18n_viz?
-      = stylesheet_link_tag("i18n_viz")
-      = javascript_tag "var i18n_viz_key_url = '#{I18nViz.key_url}';"
-      = javascript_include_tag "i18n_viz"
+#### 3. Create initializer (optional)
 
+In order to provide some custom setting for the I18nViz gem, it might make sense to create and initializer.
+
+E.g. `config/initializers/i18n_viz.rb`:
+
+    # encoding: utf-8
+    unless defined?(I18nViz).nil?
+      # determine under which condition the gem should be active
+      I18nViz.enabled = !Rails.env.production?
+        
+      # Link to display in the I18nViz tooltip
+      # e.g. pointing to that particular string in your apps translation tool
+      # the i18n key will be appended to that URL
+      I18nViz.external_tool_url = "https://webtranslateit.com/en/projects/1234567/locales/en..de/strings?utf8=✓&s="
+    end
 
-## How it works
+
+# 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:
 
@@ -59,6 +109,47 @@ The i18n_viz Javascript then parses this and enriches it into:
     
 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. ActiveRecord validations) the keys are not displayed in the frontend.
+
+
+#### Assigning I18n output to variables
+
+If you should be assigning i18n output directly into variables (e.g. within inline javascript, JS data-attributes, or other variables), the whole `--key--` thing might actually break your application.
+
+For example this usage of a data-attribute:
+
+    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--">
+
+In those cases you need to pass an additional parameter `:i18n_viz => false` to the translate method in order to not append the key.
+
+Example:
+
+    %body{:"data-date-format" => t("date.js_format", :i18n_viz => false)}
+    
+    -----
+    
+    <body data-date-format="dd.mm.yyyy">
+
+
+# Thanks
+
+Big thanks to my employer [Railslove](http://railslove.com) for supporting my open source work and to everybody who helped me.
+
+
 ### License
 
 This project is under MIT-LICENSE.

data/Rakefile

@@ -20,18 +20,38 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
 
 
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
 
+task :js_tests do
+  system("cd test/dummy")
+  system("RAILS_ENV=test rake assets:precompile")
+  system("cd ../..")
+  system("evergreen run")
+  system("cd test/dummy")
+  system("RAILS_ENV=test rake assets:clean")
+end
+
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
   t.libs << 'test'
   t.pattern = 'test/**/*_test.rb'
   t.verbose = false
+
+  #Rake::Task[:js_tests].invoke
 end
 
+task :travis do
+  ["rake test"].each do |cmd|
+    puts "Starting to run #{cmd}..."
+    system("export DISPLAY=:99.0 && bundle exec #{cmd}")
+    raise "#{cmd} failed!" unless $?.exitstatus == 0
+  end
+end
 
 task :default => :test

data/app/assets/javascripts/i18n_viz/gui.js.coffee

@@ -0,0 +1,56 @@
+$(document).ready () ->
+  # append i18n tooltip
+  $("body")
+    .append('<div id="i18n_viz_tooltip">...</div>')
+      .click () -> $("#i18n_viz_tooltip").hide()
+
+  # enrich elements with i18n attributes, classes, tooltip events
+  $.fn.initGUI = (keys) ->
+    $(this)
+      # tooltip events
+      .mouseenter () ->
+        $tooltip = $("#i18n_viz_tooltip")
+        
+        top  = $(this).offset().top - $tooltip.outerHeight()
+        left = $(this).offset().left
+        if (top < 0)
+          top = $(this).offset().top + $(this).height() + 10
+        
+        $tooltip.html('');
+        keys.forEach (value) ->
+          if (window.I18nViz.external_tool_url.length > 0)
+            $tooltip.append('<a href="' + window.I18nViz.external_tool_url + value + '" target="_blank">' + value + '</a>')
+          else
+            $tooltip.append("<span>"+value+"</span>")
+        
+        $tooltip
+          .css({top: top, left: left})
+          .show()
+    $(this)
+
+  # process elements with i18n strings in their text
+  $(":i18n-textnode").each () ->
+    $i18n_textnode = $(this)
+    i18n_keys      = window.I18nViz.extractI18nKeysFromText($i18n_textnode.text())
+
+    $i18n_textnode
+      .enrichWithI18nData(i18n_keys)
+      .initGUI(i18n_keys)
+      .clearI18nText()
+  
+  # process elements with i18n strings in the value or placeholder attributes
+  $("input:i18n-value-placeholder").each () ->
+    $i18n_input_element = $(this)
+    input_value         = $i18n_input_element.val()
+    placeholder_value   = $i18n_input_element.attr('placeholder')
+
+    i18n_keys = extractI18nKeysFromText(input_value + placeholder_value)
+
+    $i18n_input_element.enrichWithI18nData(i18n_keys)
+    
+    # clear i18n data from value and placeholder attributes
+    cleared_input_value = input_value.replace(window.I18nViz.global_regex, "")
+    $(this).val( cleared_input_value )
+    if (placeholder_value)
+      cleared_placeholder_value = placeholder_value.replace(window.I18nViz.global_regex, "")
+      $(this).attr('placeholder', cleared_placeholder_value)

data/app/assets/javascripts/i18n_viz/processing.js.coffee

@@ -0,0 +1,32 @@
+# enrich elements with i18n attributes, classes
+$.fn.enrichWithI18nData = () ->
+  i18n_keys = I18nViz.extractI18nKeysFromText $(this).text()
+  if i18n_keys != null
+    $(this)
+      .addClass("i18n-viz")
+      .data("i18n-keys", i18n_keys)
+  $(this)
+
+# clear i18n data from element text
+$.fn.clearI18nText = () ->
+  $(this).textNodes().each () ->
+    $(this).replaceWith $(this).text().replace(I18nViz.global_regex, "")
+  $(this)
+
+# extract i18n keys from a textnode (e.g. "translated text--en.translation.key--")
+I18nViz.extractI18nKeysFromText = (text) ->
+  keys = text.match(I18nViz.global_regex)
+  if keys
+    keys.forEach (value, index) -> keys[index] = value.replace(/--/g, "")
+    keys
+  else
+    null
+
+# custom :i18n selectors
+$.extend $.expr[':'], {
+  'i18n-textnode': (el) ->
+    I18nViz.regex.test $(el).textNodes().text()
+  ,
+  'i18n-value-placeholder': (el) ->
+    (I18nViz.regex.test($(el).val()) || I18nViz.regex.test($(el).attr('placeholder')))
+}

data/app/assets/javascripts/i18n_viz/settings.js.coffee.erb

@@ -0,0 +1,5 @@
+window.I18nViz = {
+  regex:             new RegExp(/--([a-z0-9_\.]+)--/i),
+  global_regex:      new RegExp(/--([a-z0-9_\.]+)--/gi),
+  external_tool_url: '<%= I18nViz.external_tool_url %>'
+}

data/app/assets/javascripts/i18n_viz/utils.js.coffee

@@ -0,0 +1,8 @@
+# get all the textnode children for an element
+# edited
+$.fn.textNodes = () ->
+  $(this).contents().filter () ->
+    try
+      (this.nodeType == 3)
+    catch err
+      false

data/app/assets/javascripts/i18n_viz.js

@@ -1,82 +1,4 @@
-$(document).ready(function(){
-  var i18n_regexp = new RegExp(/--([a-z0-9_\.]+)--/i);
-  var i18n_regexp_global = new RegExp(/--([a-z0-9_\.]+)--/gi);
-  
-  // i18n tooltip
-  $("body")
-    .append('<div id="i18n-viz-tooltip">...</div>')
-    .click(function() { $("#i18n-viz-tooltip").hide() })
-  
-  $.fn.textNodes = function() {
-    return $(this).contents().filter(function(){ return this.nodeType == 3 });
-  };
-  
-  // add i18n attributes, classes, events
-  $.fn.addI18n = function(keys) {
-    $(this)
-      .addClass("i18n-viz")
-      .data("i18n-keys", keys)
-      
-      .mouseenter(function(){
-        $tooltip = $("#i18n-viz-tooltip");
-        
-        var top = $(this).offset().top - 40;
-        var left = $(this).offset().left;
-        if (top < 0) top = $(this).offset().top + $(this).height() + 10;
-        
-        $tooltip.html('');
-        keys.forEach(function(value) {
-          if (i18n_viz_key_url) {
-            $tooltip.append('<a href="'+i18n_viz_key_url+value+'" target="_blank">'+value+'</a>')
-          } else {
-            $tooltip.append("<span>"+value+"</span>")
-          }
-        });
-        
-        $tooltip
-          .css({top: top, left: left})
-          .show()
-      })
-      .mouseleave(function() {
-        setTimeout(function() { $("#i18n-viz-tooltip").fadeOut('fast'); }, 1500);
-      });
-  };
-  
-  function getI18nKeys(text) {
-    var keys = text.match(i18n_regexp_global);
-    keys.forEach(function(value, index) { keys[index] = value.replace(/--/g, "") });
-    return keys;
-  }
-
-  // build custom :i18n selectors
-  $.extend($.expr[':'], {
-    'i18n-el': function (el) {
-      return i18n_regexp.test( $(el).textNodes().text() );
-    },
-    'i18n-value': function (el) {
-      return (i18n_regexp.test($(el).val()) || i18n_regexp.test($(el).attr('placeholder')))
-    }
-  });
-
-  $(":i18n-el").each(function(){
-    var text = $(this).text();
-    
-    var keys = getI18nKeys(text);
-    $(this).addI18n(keys);
-    
-    $(this).textNodes().each(function() { $(this).replaceWith( $(this).text().replace(i18n_regexp_global, "") ); })
-  });
-  
-  $("input:i18n-value").each(function(){
-    var value = $(this).val();
-    var placeholder = $(this).attr('placeholder');
-    var text = value + placeholder;
-    
-    var keys = getI18nKeys(text);
-    $(this).addI18n(keys);
-    
-    $(this).val(value.replace(i18n_regexp_global, ""));
-    if (placeholder) $(this).attr('placeholder', placeholder.replace(i18n_regexp_global, ""));
-  });  
-})
-
+//= require i18n_viz/settings
+//= require i18n_viz/utils
+//= require i18n_viz/processing
+//= require i18n_viz/gui

data/app/assets/stylesheets/i18n_viz.css

@@ -1,5 +1,5 @@
 /* line 4, ../../../app/stylesheets/i18n-viz.sass */
-#i18n-viz-tooltip {
+#i18n_viz_tooltip {
   display: none;
   position: absolute;
   top: 100px;
@@ -21,11 +21,11 @@
   padding: 10px;
 }
 /* line 14, ../../../app/stylesheets/i18n-viz.sass */
-#i18n-viz-tooltip a, #i18n-viz-tooltip span {
+#i18n_viz_tooltip a, #i18n_viz_tooltip span {
   margin-right: 10px;
 }
 /* line 16, ../../../app/stylesheets/i18n-viz.sass */
-#i18n-viz-tooltip a:last-child, #i18n-viz-tooltip span:last-child {
+#i18n_viz_tooltip a:last-child, #i18n_viz_tooltip span:last-child {
   margin-right: 0;
 }
 

data/app/assets/stylesheets/{i18n_viz.sass → i18n_viz.css.sass}

@@ -1,7 +1,7 @@
 @import "compass/css3/border-radius"
 @import "compass/css3/gradient"
 
-#i18n-viz-tooltip
+#i18n_viz_tooltip
   display: none
   position: absolute
   top: 100px

data/lib/generators/i18n_viz/install_generator.rb

@@ -11,7 +11,7 @@ module I18nViz
       def create_initializer
         initializer "i18n_viz.rb", %Q{
           I18nViz.enabled = !Rails.env.production?
-          I18nViz.key_url = "" # link to more information about each i18n key, e.g. "http://mytranslationtool.com/?key=" -- the key (e.g. 'en.foo.bar') will be appended to this URL
+          I18nViz.external_tool_url = "" # link to more information about each i18n key, e.g. "http://mytranslationtool.com/?key=" -- the key (e.g. 'en.foo.bar') will be appended to this URL
         }
       end
     end

data/lib/i18n_viz/version.rb

@@ -0,0 +1,3 @@
+module I18nViz
+  VERSION = "0.3.0"
+end

data/lib/i18n_viz/view_helpers.rb

@@ -3,6 +3,7 @@ module I18nViz
 
     def translate(key, options = {}) # TODO: alias
       if display_i18n_viz? && options[:i18n_viz] != false
+        # TODO: ActionController::Base.perform_caching = false  if ActionController::Base.perform_caching == true
         "#{super(key, options)}--#{key}--"
       else
         super(key, options)
@@ -14,7 +15,6 @@ module I18nViz
       return unless display_i18n_viz?
       
       stylesheet_link_tag("i18n_viz")
-      javascript_tag "var i18n_viz_key_url = '#{I18nViz.key_url}';"
       javascript_include_tag "i18n_viz"
     end
 

data/lib/i18n_viz.rb

@@ -1,5 +1,5 @@
 module I18nViz
-  mattr_accessor :key_url, :enabled
+  mattr_accessor :external_tool_url, :enabled
   
   @@enabled = true
   
@@ -9,5 +9,5 @@ module I18nViz
 end
 
 require 'i18n_viz/view_helpers'
-require 'i18n_viz/rails'
+require 'i18n_viz/engine'