i18n-hygiene 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f906fef080e1dbaa668f50b353fc861f709f1ca1
+  data.tar.gz: c79a6e97927517a08ac025ac2d8570a481de6b74
+SHA512:
+  metadata.gz: 854a7ec8e067f52e39dd77a45f649af2a9f036208c25db7e81b0a34a786bcc8fea2e986aad6d3f32c7cc678f918aa3297f69a0aea090d605c752d96e11a21bff
+  data.tar.gz: 50bc730b81a6fd89a9ea58547548f5148c96c8ed8118d780271edb07df8cd540fa8a4d4ff45b6adb3b4b7a10c5e32ce3c12da3f1c46fa7278db0754b82764548

data/lib/i18n/hygiene.rb

@@ -0,0 +1,9 @@
+require 'i18n/hygiene/railtie' if defined?(Rails)
+require 'i18n/hygiene/key_usage_checker'
+require 'i18n/hygiene/keys_with_entities'
+require 'i18n/hygiene/keys_with_matched_value'
+require 'i18n/hygiene/keys_with_return_symbol'
+require 'i18n/hygiene/keys_with_script_tags'
+require 'i18n/hygiene/locale_translations'
+require 'i18n/hygiene/variable_checker'
+require 'i18n/hygiene/wrapper'

data/lib/i18n/hygiene/key_usage_checker.rb

@@ -0,0 +1,54 @@
+module I18n
+  module Hygiene
+    # Checks the usage of i18n keys in the TC codebase.
+    #
+    # TODO: This class needs some work, I had to strip out a bunch of functionality around
+    # the dynamically used keys because it was all specific to TC.
+    #
+    # We need to add a way to configure the hygiene checks to "whitelist" certain dynamic
+    # keys and so on.
+    #
+    # The other issue is that we hard code the folders we scan for fully qualified keys
+    # which should also be configurable.
+    class KeyUsageChecker
+
+      attr_reader :key
+
+      def initialize(key)
+        @key = key
+      end
+
+      def used_in_codebase?
+        fully_qualified_key_used?
+      end
+
+      def fully_qualified_key_used?(given_key = key)
+        if pluralized_key_used?(given_key)
+          fully_qualified_key_used?(without_last_part)
+        else
+          %x<#{ag_or_ack} #{given_key} app lib | wc -l>.strip.to_i > 0
+        end
+      end
+
+      private
+
+      def ag_or_ack
+        if %x<which ag | wc -l>.strip.to_i == 1
+          return "ag"
+        else
+          return "ack --type-add=js=.coffee"
+        end
+      end
+
+      def pluralized_key_used?(key)
+        [ "zero", "one", "other" ].include?(key.split(".").last)
+      end
+
+      def without_last_part
+        key.split(".")[0..-2].join(".")
+      end
+
+    end
+
+  end
+end

data/lib/i18n/hygiene/keys_with_entities.rb

@@ -0,0 +1,29 @@
+require 'enumerator'
+
+module I18n
+  module Hygiene
+    # A collection of Strings that indicate the i18n keys in any locale that contain
+    # entities which are likely to be rendered incorrectly. Only keys ending in _html
+    # or _markdown may contain entities.
+    #
+    class KeysWithEntities
+      include Enumerable
+
+      ENTITY_REGEX = /&\w+;/
+
+      def initialize(i18nwrapper: nil)
+        @matcher = I18n::Hygiene::KeysWithMatchedValue.new(ENTITY_REGEX, i18nwrapper, reject_keys: reject_keys)
+      end
+
+      def each(&block)
+        @matcher.each(&block)
+      end
+
+      private
+
+      def reject_keys
+        Proc.new { |key| key.end_with?("_html") || key.end_with?("_markdown") }
+      end
+    end
+  end
+end

data/lib/i18n/hygiene/keys_with_matched_value.rb

@@ -0,0 +1,52 @@
+module I18n
+  module Hygiene
+    # Checks to see if any i18n values match a given regex.
+    class KeysWithMatchedValue
+      include Enumerable
+
+      def initialize(regex, i18n_wrapper = nil, reject_keys: nil)
+        @regex = regex
+        @i18n = i18n_wrapper || I18n::Hygiene::Wrapper.new
+        @reject_keys = reject_keys
+        @matching_keys = load_matching_keys
+      end
+
+      def each(&block)
+        @matching_keys.each(&block)
+      end
+
+      private
+
+      def load_matching_keys
+        locales.inject([]) do |results, locale|
+          results + matching_keys(locale).map { |key| "#{locale}: #{key}" }
+        end
+      end
+
+      def matching_keys(locale)
+        keys_to_check(locale).select { |key| i18n.value(locale, key).to_s.match(regex) }
+      end
+
+      def regex
+        @regex
+      end
+
+      def keys_to_check(locale)
+        reject_keys ? i18n.keys_to_check(locale).reject(&reject_keys) : i18n.keys_to_check(locale)
+      end
+
+      def reject_keys
+        @reject_keys
+      end
+
+      def i18n
+        @i18n
+      end
+
+      def locales
+        i18n.locales
+      end
+
+    end
+  end
+end

data/lib/i18n/hygiene/keys_with_return_symbol.rb

@@ -0,0 +1,21 @@
+require 'enumerator'
+
+module I18n
+  module Hygiene
+    # Checks to see if any i18n values contain the U+23CE character.
+    # It has been included in PhraseApp translations but is unwanted.
+    class KeysWithReturnSymbol
+      include Enumerable
+
+      RETURN_SYMBOL_REGEX = /\u23ce/
+
+      def initialize(i18n_wrapper: nil)
+        @matcher = I18n::Hygiene::KeysWithMatchedValue.new(RETURN_SYMBOL_REGEX, i18n_wrapper)
+      end
+
+      def each(&block)
+        @matcher.each(&block)
+      end
+    end
+  end
+end

data/lib/i18n/hygiene/keys_with_script_tags.rb

@@ -0,0 +1,21 @@
+require 'enumerator'
+
+module I18n
+  module Hygiene
+    # Checks to see if any i18n values contain script tags.
+    # We should never allow script tags!
+    class KeysWithScriptTags
+      include Enumerable
+
+      SCRIPT_TAG_REGEX = /<script>.*<\/script>/
+
+      def initialize(i18n_wrapper: nil)
+        @matcher = I18n::Hygiene::KeysWithMatchedValue.new(SCRIPT_TAG_REGEX, i18n_wrapper)
+      end
+
+      def each(&block)
+        @matcher.each(&block)
+      end
+    end
+  end
+end

data/lib/i18n/hygiene/locale_translations.rb

@@ -0,0 +1,74 @@
+module I18n
+  module Hygiene
+    # Wrap all translations for a single locale, with knowledge of the keys that
+    # aren't in our control. Can return the i18n keys that **are** in our control,
+    # and therefore are interesting for a variety of reasons.
+    class LocaleTranslations
+      # This is a default example key in the locale files that is not actually used.
+      EXAMPLE_KEY = "common.greeting"
+
+      # These are i18n keys provided by Rails. We cannot exclude them at the :helpers
+      # scope level because we do have some TC i18n keys scoped within :helpers.
+
+      # TODO: make this configurable
+      KEYS_TO_SKIP = [
+        "helpers.select.prompt",
+        "helpers.submit.create",
+        "helpers.submit.submit",
+        "helpers.submit.update"
+      ]
+
+      def initialize(translations)
+        @translations = translations
+      end
+
+      def keys_to_check
+        fully_qualified_keys(translations_to_check).reject { |key|
+          KEYS_TO_SKIP.include?(key) || EXAMPLE_KEY == key
+        }.sort
+      end
+
+      private
+
+      def translations_to_check
+        @translations.reject { |k, _v| non_tc_scopes.include? k }
+      end
+
+      def non_tc_scopes
+        scopes_from_rails + scopes_from_devise + scopes_from_kaminari + scopes_from_i18n_country_select + scopes_from_faker
+      end
+
+      def scopes_from_rails
+        [ :activerecord, :date, :datetime, :errors, :number, :support, :time ]
+      end
+
+      def scopes_from_devise
+        [ :devise ]
+      end
+
+      def scopes_from_kaminari
+        [ :views ]
+      end
+
+      def scopes_from_i18n_country_select
+        [ :countries ]
+      end
+
+      def scopes_from_faker
+        [ :faker ]
+      end
+
+      def fully_qualified_keys(hash)
+        hash.inject([]) do |accum, (key, value)|
+          if value.is_a?(Hash)
+            accum + fully_qualified_keys(value).map do |sub_keys|
+              "#{key}.#{sub_keys}"
+            end
+          else
+            accum + [key.to_s]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/i18n/hygiene/railtie.rb

@@ -0,0 +1,9 @@
+module I18n
+  module Hygiene
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load "tasks/i18n_hygiene.rake"
+      end
+    end
+  end
+end

data/lib/i18n/hygiene/variable_checker.rb

@@ -0,0 +1,80 @@
+module I18n
+  module Hygiene
+    # Checks for mismatching interpolation variables. For example, if the value for an i18n key
+    # as defined in :en contains an interpolation variable, the value for that key as defined
+    # in any other locale must have a matching variable name.
+    class VariableChecker
+
+      NON_ENGLISH_LOCALES_TO_CHECK = [ :fr_fr ]
+
+      def initialize(key, i18n_wrapper)
+        @key = key
+        @i18n_wrapper = i18n_wrapper
+      end
+
+      def mismatched_variables_found?
+        NON_ENGLISH_LOCALES_TO_CHECK.each do |locale|
+          if key_defined?(locale)
+            return true unless variables_match?(locale)
+          end
+        end
+        false
+      end
+
+      def mismatch_details
+        if mismatched_variables_found?
+          details_array = []
+          NON_ENGLISH_LOCALES_TO_CHECK.each do |locale|
+            if key_defined?(locale)
+              details_array << mismatch_details_for_locale(locale) unless variables_match?(locale)
+            end
+          end
+          return details_array.join("\n")
+        else
+          return "#{@key}: no missing interpolation variables found."
+        end
+      end
+
+      private
+
+      def mismatch_details_for_locale(locale)
+        "#{@key} for locale #{locale} is missing interpolation variable(s): #{missing_variables(locale)}"
+      end
+
+      def missing_variables(locale)
+        variables(:en).reject { |v| variables(locale).include?(v) }.join(', ')
+      end
+
+      def key_defined?(locale)
+        @i18n_wrapper.key_found?(locale, @key)
+      end
+
+      def variables_match?(locale)
+        variables(locale) == variables(:en)
+      end
+
+      def variables(locale)
+        collect_variables(@i18n_wrapper.value(locale, @key))
+      end
+
+      def collect_variables(string)
+        return [] unless string.is_a?(String)
+        (rails_variables(string) + js_variables(string)).uniq.sort
+      end
+
+      def rails_variables(string)
+        string.scan(/%{\S+}/).map { |var_string| var_string.gsub(/[%{}]/, '').to_sym }
+      end
+
+      def js_variables(string)
+        without_markdown_italics(string.scan(/__\S+__/).map { |var_string| var_string.gsub("__", "").to_sym })
+      end
+
+      def without_markdown_italics(array)
+        @key.end_with?("_markdown") ? [] : array
+      end
+
+    end
+
+  end
+end

data/lib/i18n/hygiene/wrapper.rb

@@ -0,0 +1,41 @@
+module I18n
+  module Hygiene
+    # Utility class for interacting with i18n definitions. This is not intended to be used
+    # in production code - it's focus is on making the i18n data easily enumerable and
+    # queryable.
+    class Wrapper
+
+      def keys_to_check(locale = :en)
+        I18n::Hygiene::LocaleTranslations.new(translations[locale]).keys_to_check
+      end
+
+      def locales
+        translations.keys
+      end
+
+      def key_found?(locale, key)
+        I18n.with_locale(locale) do
+          I18n.exists?(key)
+        end
+      end
+
+      def value(locale, key)
+        I18n.with_locale(locale) do
+          I18n.t(key)
+        end
+      end
+
+      private
+
+      def translations
+        load_translations unless @translations
+        @translations ||= ::I18n.backend.send(:translations)
+      end
+
+      def load_translations
+        ::I18n.backend.send(:init_translations)
+      end
+
+    end
+  end
+end

data/lib/tasks/i18n_hygiene.rake

@@ -0,0 +1,87 @@
+namespace :i18n do
+  namespace :hygiene do
+
+    desc 'run all the i18n hygiene checks'
+    task all: [:check_key_usage, :check_variables, :check_entities, :check_return_symbols, :check_script_tags]
+
+    desc "check usage of all EN keys"
+    task check_key_usage: :environment do
+      require 'parallel'
+
+      puts "Checking usage of EN keys..."
+      puts "(Please be patient while the codebase is searched for key usage)"
+
+      unused_keys = Parallel.map(I18n::Hygiene::Wrapper.new.keys_to_check) { |key|
+        key unless I18n::Hygiene::KeyUsageChecker.new(key).used_in_codebase?
+      }.compact
+
+      unused_keys.each do |key|
+        puts "#{key} is unused."
+      end
+
+      puts "Finished checking.\n\n"
+
+      exit(1) if unused_keys.any?
+    end
+
+    desc "check for mismatching interpolation variables"
+    task check_variables: :environment do
+      puts "Checking for mismatching interpolation variables..."
+
+      wrapper = I18n::Hygiene::Wrapper.new
+
+      mismatched_variables = wrapper.keys_to_check.select do |key|
+        checker = I18n::Hygiene::VariableChecker.new(key, wrapper)
+        checker.mismatch_details if checker.mismatched_variables_found?
+      end
+
+      mismatched_variables.each { |details| puts details }
+
+      puts "Finished checking.\n\n"
+
+      exit(1) if mismatched_variables.any?
+    end
+
+    desc "check for i18n phrases that contain entities"
+    task check_entities: :environment do
+      puts "Checking for phrases that contain entities but probably shouldn't..."
+
+      keys_with_entities = I18n::Hygiene::KeysWithEntities.new
+
+      keys_with_entities.each do |key|
+        puts "- #{key}"
+      end
+
+      puts "Finished checking.\n\n"
+
+      exit(1) if keys_with_entities.any?
+    end
+
+    desc "Check there are no values containing return symbols"
+    task check_return_symbols: :environment do
+      puts "Checking that no values contain return symbols i.e. U+23CE ..."
+
+      keys_with_return_symbols = I18n::Hygiene::KeysWithReturnSymbol.new
+
+      keys_with_return_symbols.each { |key| puts "- #{key}" }
+
+      puts "Finished checking.\n\n"
+
+      exit(1) if keys_with_return_symbols.any?
+    end
+
+    desc "Check there are no values containing scripts"
+    task check_script_tags: :environment do
+      puts "Checking that no values contain script tags ..."
+
+      keys_with_script_tags = I18n::Hygiene::KeysWithScriptTags.new
+
+      keys_with_script_tags.each { |key| puts " - #{key}" }
+
+      puts "Finished checking.\n\n"
+
+      exit(1) if keys_with_script_tags.any?
+    end
+
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: i18n-hygiene
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick Browne
+- " Keith Pitty"
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-11-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.9
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Provides rake tasks to help maintain translations.
+email: dev@theconversation.edu.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/i18n/hygiene.rb
+- lib/i18n/hygiene/key_usage_checker.rb
+- lib/i18n/hygiene/keys_with_entities.rb
+- lib/i18n/hygiene/keys_with_matched_value.rb
+- lib/i18n/hygiene/keys_with_return_symbol.rb
+- lib/i18n/hygiene/keys_with_script_tags.rb
+- lib/i18n/hygiene/locale_translations.rb
+- lib/i18n/hygiene/railtie.rb
+- lib/i18n/hygiene/variable_checker.rb
+- lib/i18n/hygiene/wrapper.rb
+- lib/tasks/i18n_hygiene.rake
+homepage: https://github.com/conversation/i18n-hygiene
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Helps maintain translations.
+test_files: []