terrestrial-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e281351eb1f04aa6331e79dcb3c229569c7886be
+  data.tar.gz: 782805e8aafda3c9fbc1af5120b59b969b7f800c
+SHA512:
+  metadata.gz: 791442b2416b61b88c2ee69daee39a8c25600e5b74f3ff2a1a74cc86a5f25326452a8c175224ec80365ee02219d15892f26cf5b74c614c6c942701f5ef742419
+  data.tar.gz: eec81b09adaa373bcef0ce1ee419721a0fe40091d61c9b8270443fd7f2a7b7e297e611d794474f9491b7bb6b0062491511167696ffead0c8b6a80a3695cfb919

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.byebug_history

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-gemset

@@ -0,0 +1 @@
+terrestrial-cli

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p648

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Niklas Begley
+
+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,134 @@
+# Terrestrial::Cli
+
+Official Terrestrial command line tool. For more documentation visit the [official docs](http://docs.terrestrial.io/).
+
+If you have any questions, join us on [Slack](https://terrestrial-slack.herokuapp.com/)!
+
+## Installation
+
+    $ gem install terrestrial-cli
+
+## Usage
+
+To get started with your project, cd to your project directory and run
+
+    $ terrestrial init --api-key <API KEY> --project-id <PROJECT ID>
+
+You can find your API key and the correct project ID by logging into [Terrestrial Mission Control](https://mission.terrestrial.io).	
+
+### First time localizing
+
+If you have not internationalized your app before, Terrestrial provides a tool for quickly extracting user-facing strings from your source code:
+
+	$ terrestrial flight
+	
+##### iOS
+	
+Flight will scan your source code and, using some clever heuristics, determine which strings can be shown to users. Terrestrial will list all the strings in terminal, and you are able to exclude any strings you wish not to internationalize.
+
+	... 
+	Page 5 of 5
+	+-------+------------------------------+------------------------------------------------+
+	| Index | String                       | File                                           |
+	+-------+------------------------------+------------------------------------------------+
+	| 40    | Home                         | InspectionMadeEasy/LeftMenuViewController.m:96 |
+	+-------+------------------------------+------------------------------------------------+
+	| 41    | Home                         | InspectionMadeEasy/MainViewController.m:23     |
+	+-------+------------------------------+------------------------------------------------+
+	-- Instructions --
+	- To exclude any strings from translation, type the index of each string.
+	-   e.g. 1,2,4
+	------------------
+	Any Exclusions? (press return to continue or 'q' to quit at any time)
+	
+	$ 
+
+After this, Terrestrial generates a **Base.lproj/Localizable.strings** file based on the selected strings, and updates your source code so that each occurence of each strings is properly referenced by ID:
+
+	# Source Code
+	label.text = @"This is my string"  =>  label.text = @"THIS_IS_MY_STRING".translated
+	
+	# The ID is generated based on the original string.
+	# The .translated method is simple syntactic sugar over NSLocalizedString, and you
+	# are able to fall back to native iOS localization APIs if needed.
+	
+**Note on Stroyboards:** Terrestrial allows you to easily use strings from your Localizable.strings files inside your Storyboards via IBInspectable properties. During the *flight* process, any strings in Storyboards will have the Terrestrial IBInspectable property turned on, and the string's ID included as a value in the properties. To see this in action, view the Attributed Inspector tab of a UI element in your Storyboards.
+	
+#### Android
+
+** Documentation coming soon **
+
+### Existing App
+
+If you have already translated your application, Terrestrial needs to know where to find your translation files. This is done via the **terrestrial.yml** file created when your project is initialized:
+
+	---
+	app_id: <app ID>
+	project_id: <project ID>
+	platform: <platform>
+	translation_files:
+	- /path/to
+	- /any/localization/files
+	
+Terrestrial will keep of the strings listed in the listed files.
+
+### Workflow
+
+As you add strings to you app, either in iOS's Localizable.strings or Android's strings.xml, you can track your changes with:
+
+	$ terrestrial scan
+	New Strings: 0
+	Removed Strings: 0
+	
+This will diff your local strings with the current strings stored in Terrestrial. You can see a breakdown of changes by running:
+
+	$ terrestrial scan --verbose
+	
+When you are ready to upload your local changes with Terrestrial for your translators to get to work, push your latest strings to Terrestrial:
+
+	$ terrestrial push
+
+We suggest running *push* as part of a standard build cycle.
+
+To get the latest translations for your app, run:
+
+	$ terrestrial pull
+
+This will update the necessary language files in your project automatically with updated translations.
+
+### Testing
+
+Terrestrial allows you to start your iOS simulator in a specified locale from the command line:
+
+	$ terrestrial ignite es  # Starts the simulator in Spanish
+
+
+To upload screenshots, along with metadata of string positions and styles, run the photoshoot command:
+
+	$ terrestrial photoshoot
+
+This will start the simulator and initialize the Terrestrial SDK in photoshoot mode. To upload screenshots to your web dashboard, just tap the injected screenshot button for each screen you wish to upload.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/terrestrial-io/terrestrial-cli.
+
+## Development
+
+To run the gem in development, run
+
+    ruby -Ilib bin/terrestrial <COMMAND>
+
+To build the gem and install it in your current Gemset, run 
+
+    rake build
+
+To run tests
+
+    rspec
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "terrestrial/cli"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/bin/terrestrial

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+require 'terrestrial'
+require 'optparse'
+
+command = ARGV[0]
+options = {}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: terrestrial <command> <options>"
+  opts.separator  ""
+  opts.separator  "Commands"
+  opts.separator  "        init             Initialize your project with Terrestrial."
+  opts.separator  "        scan             Detect any new or deleted strings in your app."
+  opts.separator  "        push             Upload the latest strings from your app."
+  opts.separator  "        pull             Download latest translations and generate relevant localization files."
+  opts.separator  "        flight           (iOS only) Find human facing strings in your app that are not currently set for translation."
+  opts.separator  "        ignite <locale>  (iOS only) Start the simulator in a specific locale."
+  opts.separator  "        photoshoot       (iOS only) Start the simulator in photoshoot mode."
+  opts.separator  ""
+  opts.separator  "Options"
+
+  opts.on("--api-key [string]", "Set and store api key") do |key|
+    options[:api_key] = key
+  end
+
+  opts.on("--project-id [integer]", "Set the app's project id") do |id|
+    options[:project_id] = id.to_i
+  end
+
+  opts.on("--verbose [boolean]", "Show additional information related to the command") do |bool|
+    options[:verbose] = true
+  end
+
+  opts.on_tail("--version", "Show version") do
+    puts "Terrestrial CLI: #{Terrestrial::Cli::VERSION}"
+    exit
+  end
+end.parse!
+
+abort "Terrestrial CLI #{Terrestrial::Cli::VERSION}" if command.nil?
+abort "Terrestrial: '#{command}' does not compute?" unless Terrestrial::Cli::COMMANDS.include? command
+
+Terrestrial::Cli.start(command, options, ARGV[1..-1])

data/circle.yml

@@ -0,0 +1,11 @@
+machine:
+  ruby:
+    version: 2.0.0
+
+dependencies:
+  pre:
+    - gem update bundler
+
+test:
+  override:
+    - bundle exec rspec -r rspec_junit_formatter --format RspecJunitFormatter -o $CIRCLE_TEST_REPORTS/rspec/junit.xml

data/lib/terrestrial/cli/android_xml_formatter.rb

@@ -0,0 +1,43 @@
+require 'rexml/document'
+
+module Terrestrial
+  module Cli
+    class AndroidXmlFormatter
+
+      def initialize(entries)
+        @entries = entries
+      end
+
+      def format_foreign_translation
+        root = REXML::Element.new("resources")
+
+        entries.each do |entry|
+          root.add_element("string", {
+            "name"    => entry.identifier 
+          }).add_text(entry.string)
+        end
+
+        print_xml(root)
+      end
+
+      def print_xml(document)
+        # In which we wrestle with REXML's insanity
+
+        REXML::Attribute.class_eval( %q^
+                                          def to_string
+                                            %Q[#@expanded_name="#{to_s().gsub(/"/, '"')}"]
+                                          end
+                                      ^)
+        formatter = Printer.new(4) # See editor/printer
+        formatter.compact = true
+        formatter.write(document,"") + "\n"
+      end
+
+      private
+
+      def entries
+        @entries
+      end
+    end
+  end
+end

data/lib/terrestrial/cli/android_xml_parser.rb

@@ -0,0 +1,49 @@
+module Terrestrial
+  module Cli
+    class AndroidXmlParser
+
+      def self.parse_file(file)
+        new(file).parse
+      end
+
+      def initialize(file)
+        @path = file
+        @file = File.new(file)
+        @document = REXML::Document.new(@file)
+      end
+
+      def parse
+        result = []
+        REXML::XPath.each(@document, "//resources/string[not(@terrestrial='false')]") do |node|
+          result << build_entry(node)
+        end
+        result
+      end
+
+      def build_entry(node)
+        Hash.new.tap do |entry|
+          entry["file"] = @path
+          entry["string"] = get_string_from_node(node)
+          entry["type"] = "strings.xml"
+          entry["identifier"] = node.attributes["name"]
+        end
+      end
+
+      def get_string_from_node(node)
+        # Why could the text be nil?
+        #  - If it contains valid XML!
+        #
+        # We assume anything inside the string tag is actually 
+        # what should be shown in the UI, so we just parse it 
+        # as a string if we realise that the parser thinks it
+        # is XML.
+
+        if !node.get_text.nil?
+          node.get_text.value
+        else
+          node.children.first.to_s
+        end
+      end
+    end
+  end
+end

data/lib/terrestrial/cli/bootstrapper.rb

@@ -0,0 +1,184 @@
+require 'delegate'
+
+module Terrestrial
+  module Cli
+    class Bootstrapper
+
+      def self.find_new_strings(directory)
+        result  = Result.new
+        entries = FileFinder.find(directory, EngineMapper::PARSERS.keys)
+          .flat_map {|file| Parser.find_strings(file) }
+          .reject   {|entry| entry["string"] == "" }
+          .select   {|entry| Parser::StringAnalyser.is_string_for_humans?(
+                               entry["string"], entry["language"], entry["variables"])}
+        
+        entries.each do |entry|
+          result.add(entry)
+        end
+        result
+      end
+    end
+
+    class Bootstrapper
+      class Result
+        include Enumerable
+
+        def initialize
+          @result_index = 0
+        end
+
+        def each(&block)
+          entries.each do |entry|
+            block.call(entry)
+          end
+        end
+
+        def each_occurence(&block)
+          entries.flat_map(&:as_separate_occurences).each do |entry|
+            block.call(entry)
+          end
+        end
+
+        def all_occurences
+          entries.flat_map(&:as_separate_occurences)
+        end
+
+        def add(entry_hash)
+          match = entries.detect {|e| e.string == entry_hash["string"] }
+          if match
+            match.add_occurence(entry_hash, next_result_index)
+          else
+            entries << Entry.from_hash(entry_hash, next_result_index)
+          end
+        end
+
+        def exclude_occurences(indexes)
+          entries.each do |entry|
+            entry.occurences.delete_if {|occurence| indexes.include? occurence.result_index }
+          end
+        end
+
+        def length
+          entries.length 
+        end
+
+        def [](i)
+          entries[i]
+        end
+
+        def entries
+          @entries ||= []
+        end
+
+        private
+
+        def next_result_index
+          @result_index += 1 
+          @result_index - 1
+        end
+      end
+    end
+
+    class Bootstrapper
+      class Entry
+        MAX_IDENTIFIER_LENGTH = 10 # words
+
+        def initialize(string, occurences = [])
+          @string = string
+          @occurences = occurences
+        end
+
+        def formatted_string
+          if occurences.any? {|occ| occ.language == :swift}
+            VariableNormalizer.run(string, swift: true)
+          else
+            VariableNormalizer.run(string)
+          end
+        end
+
+        def self.from_hash(hash, index)
+          string    = hash.fetch("string")
+          occurence = Occurence.from_hash(hash, index)
+
+          new(string, [occurence])
+        end
+
+        def identifier
+          formatted_string
+            .gsub(/%\d\$@/, '')
+            .gsub(/[^0-9a-z ]/i, '')
+            .split(" ")[0..(MAX_IDENTIFIER_LENGTH - 1)]
+            .join("_")
+            .upcase
+        end
+
+        def string
+          @string
+        end
+
+        def occurences
+          @occurences
+        end
+
+        def as_separate_occurences
+          occurences.map do |occurence|
+            EntryOccurence.new(occurence).tap do |occ|
+              occ.string     = self.string
+              occ.identifier = self.identifier
+            end
+          end
+        end
+
+        def add_occurence(hash, index)
+          if hash.fetch("string") == self.string
+            @occurences << Occurence.from_hash(hash, index)
+          else
+            raise "Add non-matching string '#{hash.fetch("string")}' as an occurence to #{self.inspect}"
+          end
+        end
+
+        class Occurence < Struct.new(:file, :line_number, :type, :language, :metadata, :result_index)
+          def self.from_hash(hash, index)
+            new.tap do |occurence|
+              occurence.file         = hash.fetch("file")
+              occurence.line_number  = hash.fetch("line_number") { nil }
+              occurence.type         = hash.fetch("type") { "unknown" }
+              occurence.language     = hash.fetch("language")
+              occurence.metadata     = hash.fetch("metadata") { Hash.new }
+              occurence.result_index = index
+            end
+          end
+        end
+
+        class EntryOccurence < SimpleDelegator
+          # Used when separating out occurences for the 
+          # editors again
+          
+          def string=(string)
+            @string = string
+          end
+
+          def string
+            @string
+          end
+
+          def identifier=(identifier)
+            @identifier = identifier
+          end
+
+          def identifier
+            @identifier
+          end
+
+          def formatted_string
+            if language == :swift
+              VariableNormalizer.run(string, swift: true)
+            else
+              VariableNormalizer.run(string)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/terrestrial/cli/command.rb

@@ -0,0 +1,20 @@
+module Terrestrial
+  module Cli
+    class Command
+
+      def initialize(opts)
+        @opts = opts
+      end
+
+      def self.run(opts = {})
+        self.new(opts).run
+      end
+
+      private
+
+      def opts
+        @opts
+      end
+    end
+  end
+end

data/lib/terrestrial/cli/detects_project_type.rb

@@ -0,0 +1,16 @@
+module Terrestrial
+  module Cli
+    class DetectsProjectType
+
+      def self.run
+        files = Dir[Config[:directory] + "/**/*"]
+
+        if files.any? {|f| f.end_with?(".xcodeproj") || f.end_with?(".xcworkspace")}
+          "ios"
+        else
+          "android"
+        end
+      end
+    end
+  end
+end

data/lib/terrestrial/cli/dot_strings_formatter.rb

@@ -0,0 +1,53 @@
+module Terrestrial
+  module Cli
+    class DotStringsFormatter
+
+      def initialize(entries)
+        @entries = entries
+      end
+
+      def format_foreign_translation
+        result = []
+        entries.each do |entry|
+          # Just ID and string needed for translation
+          # files. Extra metadata is found in Base.lproj.
+          result << "\"#{entry.identifier}\"=\"#{entry.string}\";"
+          result << ""
+        end
+        result.join("\n")
+      end
+
+      def format
+        result = []
+        entries.each do |entry|
+          result.concat(file_comments(entry))
+          result.concat(id_and_string(entry))
+          result.concat(spacing) 
+        end
+        result.join("\n")
+      end
+
+      private
+
+      def file_comments(entry)
+        ["// Files:"] + 
+          entry
+            .occurences
+            .uniq {|occ| occ.file }
+            .map  {|occ| "// - #{occ.file}" }
+      end
+
+      def id_and_string(entry)
+        ["\"#{entry.identifier}\"=\"#{entry.formatted_string}\";"]
+      end
+
+      def spacing
+        [""] # No need to put new line because of join above
+      end
+
+      def entries
+        @entries
+      end
+    end
+  end
+end