motion-phrase 0.0.1 → 0.0.2

data/README.md

@@ -1,9 +1,19 @@
-# Motion::Phrase
+# motion-phrase
 
-TODO: Write a gem description
+motion-phrase lets you connect your RubyMotion application to PhraseApp and enables you to benefit from the best internationalization workflow for your (iOS) projects.
+
+It lets you use iOS Localizable.strings files to store and read translations but at the same time work on your translation files collaboratively with translators, developers and product managers.
+
+[Learn more about PhraseApp](https://phraseapp.com/)
 
 ## Installation
 
+Using the service requires a PhraseApp account. Just sign up at [phraseapp.com/signup](https://phraseapp.com/signup) and get your free trial account (we offer free plans for small and open source projects).
+
+You can skip the introduction wizard and simply create your first project to get your Auth Token directly from the project overview in PhraseApp.
+
+### Install the Gem
+
 Add this line to your application's Gemfile:
 
     gem 'motion-phrase'
@@ -15,10 +25,106 @@ And then execute:
 Or install it yourself as:
 
     $ gem install motion-phrase
+    
+Require the gem (unless you use bundler):
+
+	require 'motion-phrase'
+    
+### Configure PhraseApp
+
+Add the Auth Token to your application's Rakefile:
+
+	Motion::Project::App.setup do |app|
+	  app.name = "Test Application"
+	  . . .
+	  app.phrase.auth_token = "YOUR_AUTH_TOKEN"
+	  . . .
+	end
+
+This will automatically create the `phrase_config.rb` configuration file in your app folder during the first build process.
+
+Now you can initialize your PhraseApp setup using rake:
+
+	rake phrase:init AUTH_TOKEN=YOUR_AUTH_TOKEN
+	
+This will:
+
+1. Create the first locale in your PhraseApp project (and make it your default locale as well)
+2. Create a `.phrase` config file that contains information required by the underlying [phrase gem](https://github.com/phrase/phrase)
 
 ## Usage
 
-TODO: Write usage instructions here
+Using PhraseApp with motion-phrase enables you to:
+
+1. Send new translations to the PhraseApp API automatically without having to write them into your Localizable.strings file or uploading them - just by browsing the app.
+2. Upload and download your most recent translations from/to the PhraseApp API using rake commands.
+3. Spend less time sending emails or fixing broken Localizable.strings files ;-)
+
+### Localizing Strings ###
+
+The first step towards a localized app is to localize all strings by extending them with their localized counterparts. This can be done by simply calling the `#__` method on each string that is implemented by motion-phrase:
+
+	"Hello World"
+	
+now becomes:
+
+	"Hello World".__
+	
+or (when using a fallback translation):
+	
+	"Hello World".__("My fallback translation")
+	
+Of course you can use more generic names for your keys as well, such as:
+
+	"HOME_WELCOME_BUTTON_LABEL".__
+	
+
+	
+[Learn more about localization in iOS](https://developer.apple.com/internationalization/)
+
+### Browsing translations in your app
+
+Simply build and run your app (in the simulator). When in development mode, motion-phrase will send all of your localized strings to PhraseApp automatically! Log into your [PhraseApp account](https://phraseapp.com/account/login) and check your newly created translation keys. If you already have your localization files in the correct place, it will transmit translations as well.
+
+### Push localization files
+
+If you already have localization files in place, you can transmit them to PhraseApp by using the following rake command:
+
+	rake phrase:push
+	
+Simply execute this from inside your project directory and it will upload all Localizable.strings files that are found in your `resources` folder. All new keys and translation will be created in your PhraseApp project during the upload.
+
+### Pull localization files
+
+Of course you want to include all recent translations in your application before releasing or testing it. Simply fetch all translations from PhraseApp using rake:
+
+	rake phrase:pull
+	
+This will download and replace all existing Localizable.strings files that sit in your `resources` folder. You can now build/test/release your application with the most recent localization files.
+
+### Extended Usage ###
+
+motion-phrase uses the [phrase gem](https://github.com/phrase/phrase) to communicate with the service. Feel free to use the `phrase` command to gain control over extended configuration options. 
+
+[Learn more about phrase gem](https://phraseapp.com/docs/installation/general-information)
+
+## Your new workflow (Best Practice)
+
+Once you have your PhraseApp integration up and running, we recommend the following workflow:
+
+1. Let developers introduce new keys (localizable strings) in the code
+2. Browse the new feature in your app
+3. Log into PhraseApp and fill out the remaining translations in all other locale (or simply order the missing translations through our expert network)
+4. Download all translations using the pull command
+5. Ship it ;-)
+
+## Important ##
+
+Please remember the following hints (especially when something goes wrong):
+
+* The locale/language that you want to send translations from must exist in your PhraseApp project (e.g. if you are running your simulator in French and want to send translations to PhraseApp by browsing the app, you first have to create a "fr" locale in your PhraseApp project)
+* We only transmit translations to the API when you run your app in development mode (`RUBYMOTION_ENV` must be development)
+* **Please double-check that no API traffic is triggered in the release/releasable version of your application!!!**
 
 ## Contributing
 
@@ -27,3 +133,8 @@ TODO: Write usage instructions here
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## Support
+
+* [PhraseApp documentation](https://phraseapp.com/docs)
+* [PhraseApp Support Channel](https://phraseapp.com/support)

data/lib/motion-phrase/api_client.rb

@@ -1,25 +1,30 @@
 module MotionPhrase
   class ApiClient
+    API_CLIENT_IDENTIFIER = "motion_phrase"
+    API_BASE_URI = "https://phraseapp.com/api/v1/"
+
     def self.sharedClient
       Dispatch.once { @instance ||= new }
       @instance
     end
 
     def storeTranslation(keyName, content, fallbackContent, currentLocale)
-      return false unless development?
+      return unless development?
       
+      content ||= fallbackContent
       data = {
-        "locale" => currentLocale,
-        "key" => keyName,
-        "content" => content,
-        "skip_verification" => true,
-        "auth_token" => PHRASE_AUTH_TOKEN
+        locale: currentLocale,
+        key: keyName,
+        content: content,
+        allow_update: false,
+        skip_verification: true,
+        api_client: API_CLIENT_IDENTIFIER,
       }
-      client.post("translations/store", data) do |result|
+      client.post("translations/store", authenticated(data)) do |result|
         if result.success?
-          log "Stored Translation for #{keyName}"
+          log "Translation stored [#{data.inspect}]"
         elsif result.failure?
-          log "Could not store translation for #{keyName}"
+          log "Error while storing translation [#{data.inspect}]"
         end
       end
     end
@@ -34,14 +39,18 @@ module MotionPhrase
     end
 
     def buildClient
-      AFMotion::Client.build_shared(PHRASE_API_BASE_URI) do
+      AFMotion::Client.build_shared(API_BASE_URI) do
         header "Accept", "application/json"
         operation :json
       end
     end
 
     def log(msg="")
-      $stdout.puts msg
+      $stdout.puts "PHRASEAPP #{msg}"
     end
+
+    def authenticated(params={})
+      params.merge(auth_token: PHRASE_AUTH_TOKEN)
+    end      
   end
 end

data/lib/motion-phrase/version.rb

@@ -1,3 +1,3 @@
 module MotionPhrase
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/motion/project/phrase.rb

@@ -5,6 +5,8 @@ end
 class PhraseConfig
   attr_accessor :auth_token
 
+  CONFIG_FILE = './app/phrase_config.rb'
+
   def initialize(config)
     @config = config
   end
@@ -18,17 +20,27 @@ private
   def create_phrase_config_file
     return unless @auth_token
 
-    code = <<EOF
+    if config_file_exists? or config_file_content_outdated?
+      File.open(CONFIG_FILE, 'w') { |f| f.write(config_file_content) }
+    end
+    files = @config.files.flatten
+    files << CONFIG_FILE unless files.find { |f| File.expand_path(f) == File.expand_path(CONFIG_FILE) }
+  end
+
+  def config_file_exists?
+    File.exist?(CONFIG_FILE)
+  end
+
+  def config_file_content_outdated?
+    File.read(CONFIG_FILE) != config_file_content
+  end
+
+  def config_file_content
+    content = <<EOF
 # This file is automatically generated. Do not edit.
 PHRASE_AUTH_TOKEN = "#{@auth_token}"
-PHRASE_API_BASE_URI = "http://localhost:3000/api/v1/"
 EOF
-    config_file = './app/phrase_config.rb'
-    unless File.exist?(config_file)
-      File.open(config_file, 'w') { |f| f.write(code) }
-    end
-    files = @config.files.flatten
-    files << config_file unless files.find { |f| File.expand_path(f) == File.expand_path(config_file) }
+    content
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: motion-phrase
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-06-04 00:00:00.000000000 Z
+date: 2013-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phrase