translation 1.9 → 1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c393ed07bd2bf4db910f2b89540920d86da3244
-  data.tar.gz: f82f7acf41fb97eccdc42eca985b6ae2b2724d21
+  metadata.gz: 74fd821b4fe211e17511bac0255df4d19e69ea53
+  data.tar.gz: 7412cec20b8b917d1117ede24162392a075fb648
 SHA512:
-  metadata.gz: 32fd1caaa72d9de52a640323cd3337609fa09d92044f2cd4747203d272b50010afde2ee97547b606f86f94c0c8d6a2b192834efc8f18822cbdf19cb3d41b7479
-  data.tar.gz: d1bd9c545975c64e8095ed7b484c2776891f61a7fd48de357b6bcde257c5444e865372ce22ff6b616d999ef9b9f5a4d660616f38dac3cadb8fd210f96958f7bc
+  metadata.gz: f06f00c70f5eb7f3daf889c2da2df86ba331da18b7f55fbfb165b76708099b6755ad9e4116eb7898d4bd001af1dc8ba1fad126929a31adf8a3cf3fc605229e40
+  data.tar.gz: 75c6637df0ed63be1e9a00afc7d395c2fc22ad9e8f79c20859eb104360ef78c9d418f611b9f613abaefcab05c3673ee086f56367beb489d45e263c7469e80416

data/README.md

@@ -1,38 +1,91 @@
 # Gem for [Translation.io](http://translation.io). [ ![Codeship Status](https://app.codeship.com/projects/f7cd4ac0-b73c-0131-51ea-522dcd2196ed/status?branch=master)](https://app.codeship.com/projects/20528) [![Code Climate](https://codeclimate.com/github/aurels/translation-gem/badges/gpa.svg)](https://codeclimate.com/github/aurels/translation-gem) [![Test Coverage](https://codeclimate.com/github/aurels/translation-gem/badges/coverage.svg)](https://codeclimate.com/github/aurels/translation-gem/coverage)
 
-## Description
+Add this gem to your [Rails](http://rubyonrails.org) application to localize
+it using [I18n (YAML)](http://guides.rubyonrails.org/i18n.html) or
+[GetText](https://github.com/ruby-gettext/gettext) syntaxes.
 
-Add this gem to your [Rails](http://rubyonrails.org) app to translate it with [Translation.io](http://translation.io).
+Keep it synchronized with your translators on [Translation.io](https://translation.io).
+
+Need help? [contact@translation.io](mailto:contact@translation.io)
 
 ## Installation
 
-Add the gem to your project's Gemfile:
+ 1. Add the gem to your project's Gemfile:
 
 ```ruby
 gem 'translation'
 ```
 
-Then:
-
-* Create a translation project [from the UI](https://translation.io).
-* Copy the initializer into your Rails app (`config/initializers/translation.rb`)
+ 2. Create a new translation project [from the UI](https://translation.io).
+ 3. Copy the initializer into your Rails app (`config/initializers/translation.rb`)
 
 The initializer looks like this:
 
 ```ruby
 TranslationIO.configure do |config|
-  config.api_key        = 'some api key which is very long'
+  config.api_key        = 'abcdefghijklmnopqrstuvwxyz012345'
   config.source_locale  = 'en'
   config.target_locales = ['fr', 'nl', 'de', 'es']
 end
 ```
 
-And finish by inititalizing your translation project with:
-
-    bundle exec rake translation:init
+ 4. Initialize your translation project with `bundle exec rake translation:init`
 
 If you later need to add/remove target languages, please read our
-[dedicated article](https://translation.io/blog/adding-target-languages) about that.
+[documentation](https://translation.io/blog/adding-target-languages) about that.
+
+## Usage
+
+#### I18n (YAML)
+
+```ruby
+# Regular
+t('inbox.title')
+
+# Plural management
+t('inbox.message', count: n)
+
+# Interpolation
+t('inbox.hello', name: @user.name)
+```
+
+...with the source YAML file:
+
+```yaml
+en:
+  inbox:
+    title:   'text to be translated'
+    message:
+      zero:  'no messages'
+      one:   'one message'
+      other: '%{count} messages'
+    hello:   'Hello %{name}'
+```
+
+You can keep your source YAML file automatically updated using [i18n-tasks](https://github.com/glebm/i18n-tasks).
+
+More information about I18n usage [here](http://guides.rubyonrails.org/i18n.html).
+
+#### GetText
+
+```ruby
+# Regular
+_("text to be translated")
+
+# Plural management
+n_("singular text", "plural text", number)
+
+# Regular with context
+p_("context", "text to be translated")
+
+# Plural management with contect
+np_("context", "singular text", "plural text", number)
+
+# Interpolations
+_('%{city1} is bigger than %{city2}') % { city1: "NYC", city2: "BXL" }
+```
+
+More information about GetText usage [here](https://github.com/ruby-gettext/gettext#usage).
 
 ## Sync
 
@@ -40,21 +93,29 @@ To send new translatable keys/strings and get new translations from Translation.
 
     bundle exec rake translation:sync
 
+## Sync and Show Purgeable
+
+If you need to see what are the unused keys/strings from Translation.io, using the current branch as reference:
+
+    bundle exec rake translation:sync_and_show_purgeable
+
+As the name says, this operation will also perform a sync at the same time.
+
 ## Sync and Purge
 
-If you also need to remove unused keys/strings from Translation.io using the current branch as reference:
+If you need to remove unused keys/strings from Translation.io, using the current branch as reference:
 
     bundle exec rake translation:sync_and_purge
 
 As the name says, this operation will also perform a sync at the same time.
 
-Warning: all keys that are not present in the current branch will be **permanently deleted both on Translation.io and in your app**.
+Warning: all keys that are not present in the current branch will be **permanently deleted from Translation.io**.
 
 ## Advanced Configuration Options
 
 The `TranslationIO.configure` block in `config/initializers/translation.rb` can take several optional configuration options.
 
-### Disable GetText
+#### Disable GetText
 
 Sometimes, you only want to use YAML and don't want to be bothered by GetText at all.
 For these cases, you just have to add `disable_gettext` in the config file.
@@ -69,7 +130,7 @@ TranslationIO.configure do |config|
 end
 ```
 
-### Ignored YAML keys
+#### Ignored YAML keys
 
 Sometimes you would like to ignore some YAML keys coming from gems or so.
 You can use the `ignored_key_prefixes` for that.
@@ -93,7 +154,27 @@ TranslationIO.configure do |config|
 end
 ```
 
-### Custom localization key prefixes
+#### Source file formats (for GetText)
+
+If you are using GetText and you want to manage other file formats than:
+
+ * `rb`, `erb`, `ruby` and `rabl` for Ruby.
+ * `haml` and `mjmlhaml` for [HAML](http://haml.info/).
+ * `slim` and `mjmlslim` for [SLIM](http://slim-lang.com/).
+
+Just add them in your configuration file like this:
+
+```ruby
+TranslationIO.configure do |config|
+  ...
+  config.source_formats      << 'rb2'
+  config.haml_source_formats << 'haml2'
+  config.slim_source_formats << 'slim2'
+  ...
+end
+```
+
+#### Custom localization key prefixes
 
 Rails YAML files contain not only translation strings but also localization values (integers, arrays, booleans)
 in the same place and that's bad. For example: date formats, number separators, default
@@ -119,7 +200,7 @@ TranslationIO.configure do |config|
 end
 ```
 
-### Paths where locales are stored (not recommended)
+#### Paths where locales are stored (not recommended)
 
 You can specify where your GetText and YAML files are on disk:
 
@@ -138,9 +219,85 @@ To run the specs:
 
     bundle exec rspec
 
+## Pure Ruby (without Rails)
+
+This gem was created specifically for Rails, but you can also use it in a pure Ruby project by making some arrangements:
+
+```ruby
+  require 'rubygems'
+  require 'active_support/all'
+  require 'yaml'
+
+  class FakeConfig
+    def after_initialize
+    end
+    def development?
+      false
+    end
+  end
+
+  module Rails
+    class Railtie
+      def self.rake_tasks
+        yield
+      end
+
+      def self.initializer(*args)
+      end
+
+      def self.config
+        ::FakeConfig.new
+      end
+    end
+
+    def self.env
+      ::FakeConfig.new
+    end
+  end
+
+  task :environment do
+  end
+
+  require 'translation'
+
+  I18n.load_path += Dir[File.join('i18n', '**', '*.{yml,yaml}')]
+
+  # Put your configuration here:
+  TranslationIO.configure do |config|
+    config.yaml_locales_path = 'i18n'
+    config.api_key           = ''
+    config.source_locale     = 'en'
+    config.target_locales    = ['nl', 'de']
+    config.metadata_path     = 'i18n/.translation_io'
+  end
+```
+
+(Thanks [@kubaw](https://github.com/kubaw) for this snippet!)
+
+## Other implementations
+
+These implementations are made by contributors for their own projects and are not
+*currently* supported by [Translation.io](https://translation.io). However, they are quite well documented.
+
+Thanks a lot to these contributors for their hard work!
+
+#### React and React-Intl (JavaScript)
+
+* GitHub: https://github.com/deecewan/translation-io
+* NPM: https://www.npmjs.com/package/translation-io
+
+Credit: [@deecewan](https://github.com/deecewan)
+
+#### Laravel (PHP)
+
+ * GitHub: https://github.com/armandsar/laravel-translationio
+ * Packagist: https://packagist.org/packages/armandsar/laravel-translationio
+
+Credit: [@armandsar](https://github.com/armandsar)
+
 ## Credits
 
-The [translation gem](https://rubygems.org/gems/translation) in released under MIT license by [Aurélien Malisart](http://aurelien.malisart.be) and [Michaël Hoste](http://80limit.com) (see MIT-LICENSE
-file).
+The [translation gem](https://rubygems.org/gems/translation) in released under MIT license by
+[Aurélien Malisart](http://aurelien.malisart.be) and [Michaël Hoste](http://80limit.com) (see LICENSE file).
 
-(c) http://translation.io
+(c) [https://translation.io](https://translation.io) / [contact@translation.io](mailto:contact@translation.io)

data/lib/translation_io/client.rb

@@ -19,8 +19,12 @@ module TranslationIO
       TranslationIO::Client::SyncOperation.new(self).run
     end
 
+    def sync_and_show_purgeable
+      TranslationIO::Client::SyncOperation.new(self).run(:show_purgeable => true)
+    end
+
     def sync_and_purge
-      TranslationIO::Client::SyncOperation.new(self).run(true)
+      TranslationIO::Client::SyncOperation.new(self).run(:purge => true)
     end
   end
 end

data/lib/translation_io/client/init_operation.rb

@@ -34,7 +34,7 @@ module TranslationIO
         warn_source_locale_unfound(source_locale, all_used_yaml_locales)
         warn_target_locale_unfound(target_locales, all_used_yaml_locales)
 
-        TranslationIO.info "Sending data to server"
+        TranslationIO.info "Sending data to server (Init may take some time, please be patient. Sync will be faster)"
         uri             = URI("#{client.endpoint}/projects/#{client.api_key}/init")
         parsed_response = BaseOperation.perform_request(uri, params)
 

data/lib/translation_io/client/sync_operation.rb

@@ -4,7 +4,10 @@ require 'translation_io/client/sync_operation/apply_yaml_source_edits_step'
 module TranslationIO
   class Client
     class SyncOperation < BaseOperation
-      def run(purge = false)
+      def run(options = {})
+        purge          = options.fetch(:purge,          false)
+        show_purgeable = options.fetch(:show_purgeable, false)
+
         config = TranslationIO.config
 
         haml_source_files = config.haml_source_files
@@ -40,12 +43,76 @@ module TranslationIO
           BaseOperation::SaveNewYamlFilesStep.new(target_locales, yaml_locales_path, parsed_response).run
           BaseOperation::SaveSpecialYamlFilesStep.new(source_locale, target_locales, yaml_locales_path, yaml_file_paths).run
 
+          display_unused_segments(parsed_response, show_purgeable, purge)
+
           info_project_url(parsed_response)
         end
 
         cleanup
       end
 
+      def display_unused_segments(parsed_response, show_purgeable, purge)
+        yaml_unused_segments    = parsed_response['unused_segments'].select { |unused_segment| unused_segment['kind'] == 'yaml' }
+        gettext_unused_segments = parsed_response['unused_segments'].select { |unused_segment| unused_segment['kind'] == 'gettext' }
+
+        yaml_size    = yaml_unused_segments.size
+        gettext_size = gettext_unused_segments.size
+        total_size   = yaml_size + gettext_size
+
+        # Quick unused segments summary for simple "sync"
+        if !show_purgeable && !purge
+          if total_size > 0
+            puts
+            puts "----------"
+            puts "#{yaml_size + gettext_size} keys/strings are in Translation.io but not in your current branch."
+            puts 'Execute "rake translation:sync_and_show_purgeable" to list these keys/strings'
+          end
+        # Complete summary for sync_and_show_purgeable or sync_and_purge
+        else
+          if purge
+            text = "were removed from Translation.io to match your current branch:"
+          elsif show_purgeable
+            text = "are in Translation.io but not in your current branch:"
+          end
+
+          if yaml_size > 0
+            puts
+            puts "----------"
+            puts "#{yaml_size} YAML #{yaml_size == 1 ? 'key' : 'keys'} #{text}"
+            puts
+
+            yaml_unused_segments.each do |yaml_unused_segment|
+              puts " - [#{yaml_unused_segment['msgctxt']}] \"#{yaml_unused_segment['msgid']}\""
+            end
+          end
+
+          if gettext_size > 0
+            puts
+            puts "----------"
+            puts "#{gettext_size} GetText #{gettext_size == 1 ? 'string' : 'strings'} #{text}"
+            puts
+
+            gettext_unused_segments.each do |gettext_unused_segment|
+              puts " - \"#{gettext_unused_segment['msgid']}\""
+            end
+          end
+
+          # Special message for when nothing need to be purged
+          if total_size == 0
+            puts
+            puts "----------"
+            puts "Nothing to purge: all the keys/strings in Translation.io are also in your current branch."
+          end
+
+          # Special message when sync_and_show_purgeable and unused segments
+          if show_purgeable && total_size > 0
+            puts
+            puts "----------"
+            puts "If you know what you are doing, you can remove them using \"rake translation:sync_and_purge\""
+          end
+        end
+      end
+
       def info_project_url(parsed_response)
         puts
         puts "----------"

data/lib/translation_io/config.rb

@@ -5,8 +5,15 @@ module TranslationIO
     attr_accessor :endpoint
     attr_accessor :verbose
     attr_accessor :test
+
     attr_accessor :ignored_key_prefixes
+    attr_accessor :ignored_source_paths
     attr_accessor :ignored_source_files
+
+    attr_accessor :source_formats
+    attr_accessor :haml_source_formats
+    attr_accessor :slim_source_formats
+
     attr_accessor :localization_key_prefixes
     attr_accessor :disable_gettext
     attr_accessor :charset
@@ -26,18 +33,25 @@ module TranslationIO
       self.endpoint                  = 'https://translation.io/api'
       self.verbose                   = 1
       self.test                      = false
+
       self.ignored_key_prefixes      = []
+      self.ignored_source_paths      = ['vendor/', 'tmp/']
       self.ignored_source_files      = [] # Files not parsed for GetText entries
+
+      self.source_formats            = ['rb', 'erb', 'ruby', 'rabl']
+      self.haml_source_formats       = ['haml', 'mjmlhaml']
+      self.slim_source_formats       = ['slim', 'mjmlslim']
+
       self.localization_key_prefixes = []
       self.disable_gettext           = false
       self.charset                   = 'UTF-8'
       self.metadata_path             = File.join('config', 'locales', '.translation_io')
 
-      self.pot_msgid_bugs_address = 'contact@translation.io'
-      self.pot_package_name       = File.basename(Dir.pwd)
-      self.pot_package_version    = '1.0'
-      self.pot_copyright_holder   = File.basename(Dir.pwd)
-      self.pot_copyright_year     = Date.today.year
+      self.pot_msgid_bugs_address    = 'contact@translation.io'
+      self.pot_package_name          = File.basename(Dir.pwd)
+      self.pot_package_version       = '1.0'
+      self.pot_copyright_holder      = File.basename(Dir.pwd)
+      self.pot_copyright_year        = Date.today.year
     end
 
     def pot_path
@@ -51,27 +65,33 @@ module TranslationIO
     end
 
     def source_files
-      file_paths = Dir['**/*.{rb,erb,ruby,rabl}'].select do |p|
-        !p.start_with?('vendor/') && !p.start_with?('tmp/')
-      end
-
-      file_paths - ignored_source_files
+      source_files_for_formats(source_formats)
     end
 
     def haml_source_files
-      Dir['**/*.{haml}'].select do |p|
-        !p.start_with?('vendor/') && !p.start_with?('tmp/')
-      end
+      source_files_for_formats(haml_source_formats)
     end
 
     def slim_source_files
-      Dir['**/*.{slim,mjmlslim}'].select do |p|
-        !p.start_with?('vendor/') && !p.start_with?('tmp/')
+      source_files_for_formats(slim_source_formats)
+    end
+
+    def source_files_for_formats(formats)
+      file_paths = Dir["**/*.{#{formats.join(',')}}"]
+
+      # remove ignored files
+      file_paths = file_paths - ignored_source_files
+
+      # remove ignored paths
+      ignored_source_paths.each do |ignored_source_path|
+        file_paths = file_paths.select { |file_path| !file_path.start_with?(ignored_source_path) }
       end
+
+      file_paths
     end
 
     def to_s
-      "#{api_key} - #{source_locale} => #{target_locales.join(' + ')}"
+      "API Key: #{api_key} | Languages: #{source_locale} => [#{target_locales.join(', ')}]"
     end
   end
 end

data/lib/translation_io/flat_hash.rb

@@ -77,7 +77,7 @@ module TranslationIO
                 current_object[current_key] = {}
               end
               current_object          = current_object[current_key]
-              current_object[new_key] = value if current_object.respond_to? :each
+              current_object[new_key] = value if current_object.is_a?(Hash)
 
               key_string = ''
             end

data/lib/translation_io/tasks.rb

@@ -5,33 +5,46 @@ require 'gettext/tools'
 
 namespace :translation do
 
-  DESCRIPTIONS = {
-    :init           => "Initialize your Translation.io project",
-    :sync           => "Send new translatable keys/strings and get new translations from Translation.io",
-    :sync_and_purge => "Remove unused keys/strings from Translation.io using the current branch as reference"
-  }
-
   desc "Get configuration infos of Translation gem"
   task :config => :environment do
     puts TranslationIO.config
   end
 
-  DESCRIPTIONS.each_pair do |t, description|
-    desc description
-    task t => :environment do
-      if TranslationIO.client
-        TranslationIO.client.send(t)
-      else
-        message = <<EOS
-[Error] Can't configure client. Did you set up the initializer?
-Read usage instructions here : http://translation.io/usage
-EOS
-        TranslationIO.info(message)
-      end
+  desc "Initialize your Translation.io project"
+  task :init => :environment do
+    if client_ready?
+      TranslationIO.client.init
+    end
+  end
+
+  desc "Send new translatable keys/strings and get new translations from Translation.io"
+  task :sync => :environment do
+    if client_ready?
+      TranslationIO.client.sync
     end
   end
 
-  task :purge => :environment do
-    TranslationIO.info("Purge is deprecated, please use rake 'translation:sync_and_purge' instead.")
+  desc "Sync and show unused keys/strings from Translation.io using the current branch as reference"
+  task :sync_and_show_purgeable => :environment do
+    if client_ready?
+      TranslationIO.client.sync_and_show_purgeable
+    end
+  end
+
+  desc "Sync and remove unused keys/strings from Translation.io using the current branch as reference"
+  task :sync_and_purge => :environment do
+    if client_ready?
+      TranslationIO.client.sync_and_purge
+    end
+  end
+
+  def client_ready?
+    if TranslationIO.client
+      true
+    else
+      TranslationIO.info("[Error] Can't configure client. Did you set up the initializer?\n"\
+                         "Read usage instructions here : http://translation.io/usage")
+      false
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: translation
 version: !ruby/object:Gem::Version
-  version: '1.9'
+  version: '1.10'
 platform: ruby
 authors:
 - Aurelien Malisart
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-16 00:00:00.000000000 Z
+date: 2017-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: gettext
@@ -128,7 +128,7 @@ files:
 - lib/translation_io/tasks.rb
 - lib/translation_io/yaml_conversion.rb
 - lib/translation_io/yaml_entry.rb
-homepage: http://translation.io
+homepage: https://translation.io
 licenses:
 - MIT
 metadata: {}