rails_translation_manager 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bcf654f074b115a7c80d173e821333d2b8b35b01
+  data.tar.gz: 84cea8e22ca03313c47e7432be605cee30905391
+SHA512:
+  metadata.gz: 6823237f243a4127c4c14ece436ec69212c1e481a1d11d8329649cfbcdc61177bf73f0097c1978fed353c863c83949f9eee62f616c16086f28757ce6645b5f0b
+  data.tar.gz: 2d8bc1c02272590a00a8bcbec3d002cec989f27c69e5025e65729ebf56c198089d0f29c8f7b87aaab5434642b28f2f11037a9596babdb1e096dd9ff8bda1a850

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.ruby-version

@@ -0,0 +1 @@
+2.1.4

data/.travis.yml

@@ -0,0 +1,2 @@
+rvm:
+  - 2.1.4

data/CONTRIBUTING.md

@@ -0,0 +1,7 @@
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rails_translation_manager.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+Copyright (C) 2015 HM Government (Government Digital Service)
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,188 @@
+# Rails Translation Manager
+
+Support for translation workflow in rails applications.
+
+## Nomenclature
+
+- **CSV**: comma separated values, a tabular data format which can be loaded into a
+           spreadsheet package
+- **I18n**: an abbreviation of 'internationalisation', which is the process of adding
+            support for multiple locales and languages to an application.
+            `I18n` is also the name of a ruby gem which supports
+            internationalisation in ruby applications.
+- **interpolation**: a technique used in I18n whereby data is inserted ("interpolated")
+                     into a translated string of text, for example `Hello %{name}`
+                     would become `Hello Sarah` if the variable `name` had the
+                     value `Sarah`.
+- **YAML**: yet another markup language, a textual data format used for storing
+            translation strings in rails applications
+
+## Technical documentation
+
+This gem provides a rails engine which adds rake tasks to manage translation
+files.
+
+It is intended to be included within your rails application by referencing it
+as a dependency in your `Gemfile`. You will then be able to use the rake tasks
+to manage your translation files and import/export translation strings.
+
+### Dependencies
+
+To date it has only been tested with a rails 3.2.18 app, but it should work with later (and older) rails apps as well.
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rails_translation_manager'
+```
+
+And then execute:
+
+    $ bundle
+
+The gem depends on your rails application environment so it would not make
+sense to install this gem stand-alone.
+
+### Running the application
+
+The primary usage of this gem is to support translation workflow.
+
+Once you have installed the gem into your application as described above, the
+expected usage is:
+
+1. export translations to a CSV file using:
+
+   ```
+   rake translation:export:all[target_directory]
+   ```
+
+   or
+
+   ```
+   rake translation:export[target_directory,base_locale,target_locale]
+   ```
+
+2. send the appropriate CSV file to a translator
+
+3. wait for translation to happen
+
+4. receive translation file back, check it for [character encoding issues](https://github.com/alphagov/character_encoding_cleaner)
+
+5. import the translation file using either:
+
+   ```
+   rake translation:import:all[source_directory]
+   ```
+
+   or
+
+   ```
+   rake translation:import[locale,path]
+   ```
+
+   this will generate `.yml` files for each translation
+
+6. commit any changed `.yml` files
+
+   ```
+   git add config/locale
+   git commit -m 'added new translations'
+   ```
+
+### Validation of interpolation keys
+
+A second feature supported by this library is the validation of interpolation
+keys.
+
+The I18n library supports 'interpolation' using the following syntax:
+
+```yaml
+en:
+  some_view:
+    greeting: Hello, %{name}
+```
+
+in this case the application can pass in the value of the `name` variable.
+
+If a translation includes an interpolation placeholder which has not been
+given a value by the application backend, then a runtime error will be raised.
+
+Unfortunately the placeholder variables sometimes get changed by mistake, or
+by translators who are not aware that they should not modify text within the
+special curly braces of the interpolation placeholder.
+
+This is obviously not great, and the validation task is intended to guard
+against it.
+
+It will check all translation files and report any which contain placeholders
+which do not exist in the english file.
+
+```
+$ rake translation:validate
+Success! No unexpected interpolation keys found.
+```
+
+### Rake command reference
+
+#### Export a specific locale to CSV
+
+```
+rake translation:export[directory,base_locale,target_locale]
+```
+
+#### Export all locales to CSV files
+
+```
+rake translation:export:all[directory]
+```
+
+#### Import a specific locale CSV to YAML within the app
+
+```
+rake translation:import[locale,path]
+```
+
+#### Import all locale CSV files to YAML within the app
+
+```
+rake translation:import:all[directory]
+```
+
+#### Regenerate all locales from the EN locale - run this after adding keys
+
+```
+rake translation:regenerate[directory]
+```
+
+#### Check translation files for errors
+
+```
+rake translation:validate
+```
+
+### Running the test suite
+
+To run the test suite just run `bundle exec rake` from within the
+`rails_translation_manager` directory.
+
+You will need to clone the repository locally and run `bundle install` the
+first time you do this, eg.:
+
+```sh
+$ git clone git@github.com:alphagov/rails_translation_manager.git
+$ cd rails_translation_manager
+$ bundle install
+$ bundle exec rake
+...
+```
+
+## Licence
+
+[MIT License](LICENSE.txt)
+
+## Versioning policy
+
+We use [semantic versioning](http://semver.org/), and bump the version
+on master only. Please don't submit your own proposed version numbers.

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new("test") do |t|
+  t.description = "Run tests"
+  t.ruby_opts << "-rubygems"
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.verbose = true
+end
+
+task :default => :test

data/lib/rails_translation_manager/exporter.rb

@@ -0,0 +1,111 @@
+# encoding: utf-8
+require "yaml"
+require "csv"
+require 'i18n'
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/hash/keys.rb"
+
+class RailsTranslationManager::Exporter
+  def initialize(directory, source_locale_path, target_locale_path)
+    @source_locale_path = source_locale_path
+    @target_locale_path = target_locale_path
+    @source_locale = File.basename(target_locale_path).split(".")[0]
+    @target_locale = File.basename(target_locale_path).split(".")[0]
+    @output_path = File.join(directory, @target_locale + ".csv")
+
+    @keyed_source_data = translation_file_to_keyed_data(source_locale_path, @source_locale)
+    @keyed_target_data = translation_file_to_keyed_data(target_locale_path, @target_locale)
+  end
+
+  def export
+    csv = CSV.generate do |csv|
+      csv << CSV::Row.new(["key", "source", "translation"], ["key", "source", "translation"], true)
+      @keyed_source_data.keys.sort.each do |key|
+        if key =~ /^language_names\./
+          next unless key =~ /#{@target_locale}$/
+        end
+        if is_pluralized_key?(key)
+          export_pluralization_rows(key, csv)
+        else
+          csv << export_row(key, @keyed_source_data[key], @keyed_target_data[key])
+        end
+      end
+    end
+    File.open(@output_path, "w") { |f| f.write csv.to_s }
+  end
+
+  private
+
+  def export_pluralization_rows(key, csv)
+    I18n.t('i18n.plural.keys', locale: @target_locale).map(&:to_s).each do |plural_key|
+      csv << export_row(depluralized_key_for(key, plural_key), @keyed_source_data.fetch(key, {})[plural_key], @keyed_target_data.fetch(key, {})[plural_key])
+    end
+  end
+
+  def export_row(key, source_value, target_value)
+    CSV::Row.new(['key', 'source', 'translation'], [key, source_value, target_value])
+  end
+
+  def translation_file_to_keyed_data(path, locale)
+    if File.exist?(path)
+      hash = YAML.load_file(path).values[0]
+      hash_to_keyed_data("", hash, locale)
+    else
+      {}
+    end
+  end
+
+  def hash_to_keyed_data(prefix, hash, locale)
+    if hash_is_for_pluralization?(hash, locale)
+      {pluralized_prefix(prefix) => hash.stringify_keys}
+    else
+      results = {}
+      hash.each do |key, value|
+        if value.is_a?(Hash)
+          results.merge!(hash_to_keyed_data(key_for(prefix, key), value, locale))
+        else
+          results[key_for(prefix, key)] = value
+        end
+      end
+      results
+    end
+  end
+
+  # if the hash is only made up of the plural keys for the locale, we
+  # assume it's a plualization set.  Note that zero is *always* an option
+  # regardless of the keys fetched
+  # (see https://github.com/svenfuchs/i18n/blob/master/lib/i18n/backend/pluralization.rb#L34)
+  def hash_is_for_pluralization?(hash, locale)
+    plural_keys = I18n.t('i18n.plural.keys', locale: locale)
+    raise missing_pluralisations_message(locale) unless plural_keys.is_a?(Array)
+    ((hash.keys.map(&:to_s) - plural_keys.map(&:to_s)) - ['zero']).empty?
+  end
+
+  def missing_pluralisations_message(locale)
+    "No pluralization forms defined for locale '#{locale}'. " +
+    "This probably means that the rails-18n gem does not provide a " +
+    "definition of the plural forms for this locale, you may need to " +
+    "define them yourself."
+  end
+
+  def key_for(prefix, key)
+    prefix.blank? ? key.to_s : "#{prefix}.#{key}"
+  end
+
+  def is_pluralized_key?(key)
+    key =~ /\APLURALIZATION\-KEY\:/
+  end
+
+  def pluralized_prefix(prefix)
+    if is_pluralized_key?(prefix)
+      prefix
+    else
+      "PLURALIZATION-KEY:#{prefix}"
+    end
+  end
+
+  def depluralized_key_for(prefix, key)
+    depluralized_prefix = prefix.gsub(/\APLURALIZATION\-KEY\:/, '')
+    key_for(depluralized_prefix, key)
+  end
+end

data/lib/rails_translation_manager/importer.rb

@@ -0,0 +1,60 @@
+require "yaml"
+require "csv"
+
+class RailsTranslationManager::Importer
+  def initialize(locale, csv_path, import_directory)
+    @csv_path = csv_path
+    @locale = locale
+    @import_directory = import_directory
+  end
+
+  def import
+    csv = CSV.read(@csv_path, headers: true, header_converters: :downcase)
+    data = {}
+    csv.each do |row|
+      key = row["key"]
+      key_parts = key.split(".")
+      if key_parts.length > 1
+        leaf_node = (data[key_parts.first] ||= {})
+        key_parts[1..-2].each do |part|
+          leaf_node = (leaf_node[part] ||= {})
+        end
+        leaf_node[key_parts.last] = parse_translation(row["translation"])
+      else
+        data[key_parts.first] = parse_translation(row["translation"])
+      end
+    end
+
+    File.open(import_yml_path, "w") do |f|
+      yaml = {@locale.to_s => data}.to_yaml(separator: "")
+      yaml_without_header = yaml.split("\n").map { |l| l.gsub(/\s+$/, '') }[1..-1].join("\n")
+      f.write(yaml_without_header)
+      f.puts
+    end
+  end
+
+  private
+
+  def import_yml_path
+    File.join(@import_directory, "#{@locale}.yml")
+  end
+
+  def parse_translation(translation)
+    if translation =~ /^\[/
+      values = translation.gsub(/^\[/, '').gsub(/\]$/, '').gsub("\"", '').split(/\s*,\s*/)
+      values.map { |v| parse_translation(v) }
+    elsif translation =~ /^:/
+      translation.gsub(/^:/, '').to_sym
+    elsif translation =~ /^true$/
+      true
+    elsif translation =~ /^false$/
+      false
+    elsif translation =~ /^\d+$/
+      translation.to_i
+    elsif translation == "nil"
+      nil
+    else
+      translation
+    end
+  end
+end

data/lib/rails_translation_manager/railtie.rb

@@ -0,0 +1,9 @@
+require 'rails_translation_manager'
+
+module RailsTranslationManager
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      Dir[File.expand_path('../tasks/*.rake', File.dirname(__FILE__))].each { |f| load f }
+    end
+  end
+end

data/lib/rails_translation_manager/validator.rb

@@ -0,0 +1,92 @@
+require 'yaml'
+require 'logger'
+
+class RailsTranslationManager::Validator
+  def initialize(translation_file_path, logger = Logger.new(nil))
+    @translation_file_path = translation_file_path
+    @logger = logger
+  end
+
+  def check!
+    @logger.info "Checking translation files in '#{@translation_file_path}' for unexpected interpolation keys"
+    @logger.info "Loading reference file (#{reference_file_name})"
+    @logger.info "Checking..."
+    reference = load_translation_file("#{@translation_file_path}/#{reference_file_name}")
+    Dir["#{@translation_file_path}/*.yml"].reject do |entry|
+      File.basename(entry) == reference_file_name
+    end.inject([]) do |errors, entry|
+      translation_file = load_translation_file(entry)
+      errors + unexpected_substitution_keys(reference, translation_file)
+    end
+  end
+
+  def unexpected_substitution_keys(reference, translation_file)
+    reference_substitutions = substitutions_in(reference)
+    target_substitutions = substitutions_in(translation_file)
+
+    targets_by_path = target_substitutions.each_with_object({}) do |target, hash|
+      hash[exclude_locale_from_path(target.path)] = target
+    end
+
+    reference_substitutions.each_with_object([]) do |reference, unexpected_substitutions|
+      target = targets_by_path[exclude_locale_from_path(reference.path)]
+      next if target.nil? || reference.has_all_substitutions?(target)
+      unexpected_substitutions << UnexpectedSubstition.new(target, reference)
+    end
+  end
+
+  def substitutions_in(translation_file)
+    flatten(translation_file).reject do |translation|
+      translation.substitutions.empty?
+    end
+  end
+
+  class TranslationEntry < Struct.new(:path, :value)
+    def substitutions
+      @substitutions ||= self.value.scan(/%{([^}]*)}/)
+    end
+
+    def has_all_substitutions?(other)
+      (other.substitutions - self.substitutions).empty?
+    end
+  end
+
+  class UnexpectedSubstition < Struct.new(:target, :reference)
+    def to_s
+      missing = (self.reference.substitutions - self.target.substitutions)
+      extras = (self.target.substitutions - self.reference.substitutions)
+      message = %Q{Key "#{target.path.join('.')}":}
+      if extras.any?
+        message << %Q{ Extra substitutions: ["#{extras.join('", "')}"].}
+      end
+      if missing.any?
+        message << %Q{ Missing substitutions: ["#{missing.join('", "')}"].}
+      end
+      message
+    end
+  end
+
+  def flatten(translation_file, path = [])
+    translation_file.map do |key, value|
+      case value
+      when Hash
+        flatten(value, path + [key])
+      else
+        TranslationEntry.new(path + [key], value || "")
+      end
+    end.flatten
+  end
+
+  def load_translation_file(filename)
+    YAML.load_file(filename)
+  end
+
+  def reference_file_name
+    "en.yml"
+  end
+
+private
+  def exclude_locale_from_path(path)
+    path[1..-1]
+  end
+end

data/lib/rails_translation_manager/version.rb

@@ -0,0 +1,3 @@
+module RailsTranslationManager
+  VERSION = "0.0.1"
+end

data/lib/rails_translation_manager.rb

@@ -0,0 +1,8 @@
+require "rails_translation_manager/version"
+require "rails_translation_manager/railtie" if defined?(Rails)
+require "rails-i18n"
+
+module RailsTranslationManager
+  autoload :Exporter, "rails_translation_manager/exporter"
+  autoload :Importer, "rails_translation_manager/importer"
+end

data/lib/tasks/translation.rake

@@ -0,0 +1,70 @@
+$LOAD_PATH.unshift(File.expand_path("../.."), __FILE__)
+require "rails_translation_manager"
+
+namespace :translation do
+
+  desc "Regenerate all locales from the EN locale - run this after adding keys"
+  task(:regenerate, [:directory] => [:environment]) do |t, args|
+    directory = args[:directory] || "tmp/locale_csv"
+
+    Rake::Task["translation:export:all"].invoke(directory)
+    Rake::Task["translation:import:all"].invoke(directory)
+  end
+
+  desc "Export a specific locale to CSV."
+  task :export, [:directory, :base_locale, :target_locale] => [:environment] do |t, args|
+    FileUtils.mkdir_p(args[:directory]) unless File.exist?(args[:directory])
+    base_locale = Rails.root.join("config", "locales", args[:base_locale] + ".yml")
+    target_locale_path = Rails.root.join("config", "locales", args[:target_locale] + ".yml")
+    exporter = RailsTranslationManager::Exporter.new(args[:directory], base_locale, target_locale_path)
+    exporter.export
+  end
+
+  namespace :export do
+    desc "Export all locales to CSV files."
+    task :all, [:directory] => [:environment] do |t, args|
+      directory = args[:directory] || "tmp/locale_csv"
+      FileUtils.mkdir_p(directory) unless File.exist?(directory)
+      locales = Dir[Rails.root.join("config", "locales", "*.yml")]
+      base_locale = Rails.root.join("config", "locales", "en.yml")
+      target_locales = locales - [base_locale.to_s]
+      target_locales.each do |target_locale_path|
+        exporter = RailsTranslationManager::Exporter.new(directory, base_locale, target_locale_path)
+        exporter.export
+      end
+      puts "Exported locale CSV to #{directory}"
+    end
+  end
+
+  desc "Import a specific locale CSV to YAML within the app."
+  task :import, [:locale, :path] => [:environment] do |t, args|
+    importer = RailsTranslationManager::Importer.new(args[:locale], args[:path], Rails.root.join("config", "locales"))
+    importer.import
+  end
+
+  namespace :import do
+    desc "Import all locale CSV files to YAML within the app."
+    task :all, [:directory] => [:environment] do |t, args|
+      directory = args[:directory] || "tmp/locale_csv"
+      Dir[File.join(directory, "*.csv")].each do |csv_path|
+        locale = File.basename(csv_path, ".csv")
+        importer = RailsTranslationManager::Importer.new(locale, csv_path, Rails.root.join("config", "locales"))
+        importer.import
+      end
+    end
+  end
+
+  desc "Check translation files for errors"
+  task :validate do
+    require 'rails_translation_manager/validator'
+    logger = Logger.new(STDOUT)
+    validator = RailsTranslationManager::Validator.new(Rails.root.join('config', 'locales'), logger)
+    errors = validator.check!
+    if errors.any?
+      puts "Found #{errors.size} errors:"
+      puts errors.map(&:to_s).join("\n")
+    else
+      puts "Success! No unexpected interpolation keys found."
+    end
+  end
+end

data/rails_translation_manager.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rails_translation_manager/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rails_translation_manager"
+  spec.version       = RailsTranslationManager::VERSION
+  spec.authors       = ["Edd Sowden"]
+  spec.email         = ["edd.sowden@digital.cabinet-office.gov.uk"]
+  spec.summary       = %q{Tasks to manage translation files}
+  spec.description   = ""
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails-i18n"
+  spec.add_dependency "activesupport"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+end

data/test/rails_translation_manager/exporter_test.rb

@@ -0,0 +1,239 @@
+require "test_helper"
+
+require "rails_translation_manager/exporter"
+require "tmpdir"
+require "csv"
+require "i18n"
+
+module RailsTranslationManager
+  class ExporterTest < Minitest::Test
+
+    def setup
+      # fast test helper means we have to setup the pluralizations we're
+      # going to use manually as rails-i18n does it in the rails app
+      I18n.backend.class.send(:include, I18n::Backend::Pluralization)
+      I18n.available_locales = [:fr, :es, :ar, :sk, :uk]
+      with_pluralization_forms(
+        'fr' => [:one, :other],
+        'es' => [:one, :other],
+        'ar' => [:zero, :one, :two, :few, :many, :other],
+        'sk' => [:one, :few, :other],
+        'uk' => [:one, :few, :many, :other]
+      )
+    end
+
+    test 'should export CSV file for filling in a given translation' do
+      given_locale(:en, {
+        world_location: {
+          type: {
+            country: "Country"
+          },
+          country: "Spain",
+          headings: {
+            mission: "Our mission",
+            offices: "Offices"
+          }
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:fr)).export
+
+      assert File.file?(exported_file("fr.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("fr.csv"))
+      assert_equal ["Country", nil], data["world_location.type.country"]
+      assert_equal ["Spain", nil], data["world_location.country"]
+      assert_equal ["Our mission", nil], data["world_location.headings.mission"]
+      assert_equal ["Offices", nil], data["world_location.headings.offices"]
+    end
+
+    test 'should include any existing translations in the output file' do
+      given_locale(:en, {
+        world_location: {
+          type: {
+            country: "Country"
+          },
+          country: "Spain",
+          headings: {
+            mission: "Our mission",
+            offices: "Offices"
+          }
+        }
+      })
+      given_locale(:fr, {
+        world_location: {
+          type: {
+            country: "Pays"
+          },
+          country: "Espange"
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:fr)).export
+
+      assert File.file?(exported_file("fr.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("fr.csv"))
+      assert_equal ["Country", "Pays"], data["world_location.type.country"]
+      assert_equal ["Spain", "Espange"], data["world_location.country"]
+      assert_equal ["Our mission", nil], data["world_location.headings.mission"]
+      assert_equal ["Offices", nil], data["world_location.headings.offices"]
+    end
+
+    test 'should not include any language names that are not English or the native in the output file' do
+      given_locale(:en, {
+        language_names: {
+          en: "English",
+          es: "Spanish",
+          fr: "French"
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:fr)).export
+
+      assert File.file?(exported_file("fr.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("fr.csv"))
+      assert_equal ["French", nil], data["language_names.fr"]
+      assert_equal nil, data["language_names.es"], "language key for spanish should not be present"
+    end
+
+    test 'should export correct pluralization forms for target' do
+      given_locale(:en, {
+        ministers: {
+          one: 'minister',
+          other: 'ministers'
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:ar)).export
+
+      assert File.file?(exported_file("ar.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("ar.csv"))
+      ['zero', 'one', 'two', 'few', 'many', 'other'].each do |arabic_plural_form|
+        assert data.has_key?("ministers.#{arabic_plural_form}"), "expected plural form #{arabic_plural_form} to be present, but it's not"
+      end
+    end
+
+    test 'should export source pluralization forms values to target when the forms match' do
+      given_locale(:en, {
+        ministers: {
+          one: 'minister',
+          other: 'ministers'
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:sk)).export
+
+      assert File.file?(exported_file("sk.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("sk.csv"))
+      assert_equal ['minister', nil], data['ministers.one']
+      assert_equal ['ministers', nil], data['ministers.other']
+      assert_equal [nil, nil], data['ministers.few']
+    end
+
+    test 'should keep existing target pluralization form values' do
+      given_locale(:en, {
+        ministers: {
+          one: 'minister',
+          other: 'ministers'
+        }
+      })
+      given_locale(:sk, {
+        ministers: {
+          one: 'min',
+          few: 'mini'
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:sk)).export
+
+      assert File.file?(exported_file("sk.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("sk.csv"))
+      assert_equal ['minister', 'min'], data['ministers.one']
+      assert_equal ['ministers', nil], data['ministers.other']
+      assert_equal [nil, 'mini'], data['ministers.few']
+    end
+
+    test 'should allow for zero keys when detecting pluralization forms' do
+      given_locale(:en, {
+        ministers: {
+          zero: 'no ministers',
+          one: 'minister',
+          other: 'ministers'
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:uk)).export
+
+      assert File.file?(exported_file("uk.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("uk.csv"))
+      ['one', 'few', 'many', 'other'].each do |ukranian_plural_form|
+        assert data.has_key?("ministers.#{ukranian_plural_form}"), "expected plural form #{ukranian_plural_form} to be present, but it's not"
+      end
+    end
+
+    test 'should leave keys alone if the hash doesn\'t look like it only contains pluralization forms' do
+      given_locale(:en, {
+        ministers: {
+          one: 'minister',
+          other: 'ministers',
+          monkey: 'monkey'
+        }
+      })
+
+      Exporter.new(export_directory, locale_path(:en), locale_path(:uk)).export
+
+      assert File.file?(exported_file("uk.csv")), "should write a file"
+
+      data = read_csv_data(exported_file("uk.csv"))
+      ['few', 'many'].each do |ukranian_plural_form|
+        refute data.has_key?("ministers.#{ukranian_plural_form}"), "expected plural form #{ukranian_plural_form} to be missing, but it's present"
+      end
+      ['one', 'other', 'monkey'].each do |non_plural_forms|
+        assert data.has_key?("ministers.#{non_plural_forms}"), "expected non-plural form #{non_plural_forms} to be present, but it's not"
+      end
+    end
+
+  private
+
+    def read_csv_data(file)
+      csv = CSV.read(file, headers: true)
+      csv.inject({}) { |h, row| h[row["key"]] = [row["source"], row["translation"]]; h }
+    end
+
+    def given_locale(locale, keys)
+      File.open(locale_path(locale), "w") do |f|
+        f.puts({locale => keys}.to_yaml)
+      end
+    end
+
+    def locale_path(locale)
+      File.join(export_directory, "#{locale}.yml")
+    end
+
+    def exported_file(name)
+      File.new(File.join(export_directory, name))
+    end
+
+    def export_directory
+      @tmpdir ||= Dir.mktmpdir
+    end
+
+    def with_pluralization_forms(pluralizations)
+      pluralizations.each do |locale, pluralization_forms|
+        I18n.backend.store_translations(locale, {
+          'i18n' => {
+            'plural' => {
+              'keys' => pluralization_forms
+            }
+          }
+        })
+      end
+    end
+  end
+end

data/test/rails_translation_manager/importer_test.rb

@@ -0,0 +1,166 @@
+require "test_helper"
+require "rails_translation_manager/importer"
+require "tmpdir"
+require "csv"
+
+module RailsTranslationManager
+  class ImporterTest < Minitest::Test
+    test 'should create a new locale file for a filled in translation csv file' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["world_location.type.country", "Country", "Pays"],
+        ["world_location.country", "Germany", "Allemange"],
+        ["other.nested.key", "original", "translated"]
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      yaml_translation_data = YAML.load_file(File.join(import_directory, "fr.yml"))
+      expected = {"fr" => {
+        "world_location" => {
+          "country" => "Allemange",
+          "type" => {
+            "country" => "Pays"
+          }
+        },
+        "other" => {
+          "nested" => {
+            "key" => "translated"
+          }
+        }
+      }}
+      assert_equal expected, yaml_translation_data
+    end
+
+    test 'outputs YAML without the header --- line for consistency with convention' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["key", "value", "le value"],
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      assert_equal "fr:", File.readlines(File.join(import_directory, "fr.yml")).first.strip
+    end
+
+    test 'outputs a newline at the end of the YAML for consistency with code editors' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["key", "value", "le value"],
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      assert_match /\n$/, File.readlines(File.join(import_directory, "fr.yml")).last
+    end
+
+    test 'strips whitespace from the end of lines for consistency with code editors' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["key", "value", nil],
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      lines = File.readlines(File.join(import_directory, "fr.yml"))
+      refute lines.any? { |line| line =~ /\s\n$/ }
+    end
+
+    test 'imports arrays from CSV as arrays' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["fruit", ["Apples", "Bananas", "Pears"], ["Pommes", "Bananes", "Poires"]]
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      yaml_translation_data = YAML.load_file(File.join(import_directory, "fr.yml"))
+      expected = {"fr" => {
+        "fruit" => ["Pommes", "Bananes", "Poires"]
+      }}
+      assert_equal expected, yaml_translation_data
+    end
+
+    test 'interprets string "nil" as nil' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["things", ["one", nil, "two"], ["une", nil, "deux"]]
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      yaml_translation_data = YAML.load_file(File.join(import_directory, "fr.yml"))
+      expected = {"fr" => {
+        "things" => ["une", nil, "deux"]
+      }}
+      assert_equal expected, yaml_translation_data
+    end
+
+    test 'interprets string ":thing" as symbol' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["sentiment", ":whatever", ":bof"]
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      yaml_translation_data = YAML.load_file(File.join(import_directory, "fr.yml"))
+      expected = {"fr" => {
+        "sentiment" => :bof
+      }}
+      assert_equal expected, yaml_translation_data
+    end
+
+    test 'interprets integer strings as integers' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["price", "123", "123"]
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      yaml_translation_data = YAML.load_file(File.join(import_directory, "fr.yml"))
+      expected = {"fr" => {
+        "price" => 123
+      }}
+      assert_equal expected, yaml_translation_data
+    end
+
+    test 'interprets boolean values as booleans, not strings' do
+      given_csv(:fr,
+        [:key, :source, :translation],
+        ["key1", "is true", "true"],
+        ["key2", "is false", "false"]
+      )
+
+      Importer.new(:fr, csv_path(:fr), import_directory).import
+
+      yaml_translation_data = YAML.load_file(File.join(import_directory, "fr.yml"))
+      expected = {"fr" => {
+        "key1" => true,
+        "key2" => false
+      }}
+      assert_equal expected, yaml_translation_data
+    end
+
+  private
+
+    def csv_path(locale)
+      File.join(import_directory, "#{locale}.csv")
+    end
+
+    def given_csv(locale, header_row, *rows)
+      csv = CSV.generate do |csv|
+        csv << CSV::Row.new(["key", "source", "translation"], ["key", "source", "translation"], true)
+        rows.each do |row|
+          csv << CSV::Row.new(["key", "source", "translation"], row)
+        end
+      end
+      File.open(csv_path(locale), "w") { |f| f.write csv.to_s }
+    end
+
+    def import_directory
+      @import_directory ||= Dir.mktmpdir
+    end
+  end
+end

data/test/rails_translation_manager/validator_test.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+require 'test_helper'
+require 'rails_translation_manager/validator'
+require 'tmpdir'
+require 'fileutils'
+
+module RailsTranslationManager
+  class ValidatorTest < Minitest::Test
+    def setup
+      @translation_path = Dir.mktmpdir
+      @translation_validator = Validator.new(@translation_path)
+    end
+
+    def teardown
+      FileUtils.remove_entry_secure(@translation_path)
+    end
+
+    def create_translation_file(locale, content)
+      File.open(File.join(@translation_path, "#{locale}.yml"), "w") do |f|
+        f.write(content.lstrip)
+      end
+    end
+
+    test "can create a flattened list of substitutions" do
+      translation_file = YAML.load(%q{
+en:
+  view: View '%{title}'
+  test: foo
+})
+      expected = [Validator::TranslationEntry.new(%w{en view}, "View '%{title}'")]
+      assert_equal expected, @translation_validator.substitutions_in(translation_file)
+    end
+
+    test "detects extra substitution keys" do
+      create_translation_file("en", %q{
+en:
+  document:
+    view: View '%{title}'
+})
+      create_translation_file("sr", %q{
+sr:
+  document:
+    view: Pročitajte '%{naslov}'
+})
+      errors = Validator.new(@translation_path).check!
+
+      expected = %q{Key "sr.document.view": Extra substitutions: ["naslov"]. Missing substitutions: ["title"].}
+      assert_equal [expected], errors.map(&:to_s)
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+require 'minitest/autorun'
+
+module SimpleTestDsl
+  def test(name, &block)
+    define_method "test_#{name}", &block
+  end
+end
+
+Minitest::Test.extend(SimpleTestDsl)

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: rails_translation_manager
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Edd Sowden
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails-i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ''
+email:
+- edd.sowden@digital.cabinet-office.gov.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-version"
+- ".travis.yml"
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rails_translation_manager.rb
+- lib/rails_translation_manager/exporter.rb
+- lib/rails_translation_manager/importer.rb
+- lib/rails_translation_manager/railtie.rb
+- lib/rails_translation_manager/validator.rb
+- lib/rails_translation_manager/version.rb
+- lib/tasks/translation.rake
+- rails_translation_manager.gemspec
+- test/rails_translation_manager/exporter_test.rb
+- test/rails_translation_manager/importer_test.rb
+- test/rails_translation_manager/validator_test.rb
+- test/test_helper.rb
+homepage: ''
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Tasks to manage translation files
+test_files:
+- test/rails_translation_manager/exporter_test.rb
+- test/rails_translation_manager/importer_test.rb
+- test/rails_translation_manager/validator_test.rb
+- test/test_helper.rb