fame 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aaa07dd2ecd76f2cf02be0a769acc8fe9f982a3d
+  data.tar.gz: d7a888bfbd6a93c52037b6088249b8c116abbab1
+SHA512:
+  metadata.gz: 48b11deac64f15a42d05ee456f2e167fc04d352228b6d63e992cfb6c4ac6ad64c34d665826f1a9b09a0db309d94533a7b3140bb7834ddcb0a594ec8e56ffd8ef
+  data.tar.gz: 45064b46d5fb314057bde5b2f0e2452b3b82217ef63659736b164865757dd519c3567bd046ff036d4b14a053c6b3ab57aab3b07cf0e7a71dcffd3a8390b5820d

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2016 Alexander Schuch
+
+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,133 @@
+# Fame
+
+Delightful localization of .storyboard and .xib files, right within Interface Builder.
+
+Fame makes it easy to enable specific Interface Builder elements to be translated and exported to localizable .strings files.
+
+## Introduction
+
+Compared to localization in code (`NSLocalizedString`), Storyboard and XIB localizations are a tedious task for both developers and translators.
+
+#### Static vs. dynamic localization
+
+Storyboard and XIB files usually contain a mixed set of elements with *static* or *dynamic* text:
+* **Static text**: Elements with fixed localization strings that will never change at runtime
+* **Dynamic text**: Elements that will change their localized text during runtime. For example a label that is populated with data from an API or a status label that is populated using `NSLocalizedString` at runtime.
+
+**Static text elements should be localized using a generated .strings file, dynamic text elements should be ignored during translation.**
+
+However, Storyboard and XIB .stings files generated by Xcode also contain dynamic text localizations that will always be overridden at runtime. This makes it hard to distinguish between localizations that should be translated and dynamic text that can be safely ignored during translation.
+Its up to the app developers to either manually remove generated localizations that should not be translated, or leave them for the translators to waste their time with.
+
+#### Localization comments
+
+Storyboard and XIB .stings files generated by Xcode **do not provide a useful comment that provides context to the translator**.
+
+```css
+/* Class = "UILabel"; text = "Label"; ObjectID = "Rfi-2u-xEd"; */
+"Rfi-2u-xEd.text" = "Label";
+```
+
+Translators use this comment to make sure their translation fits into the context it is used in. Its again up to the app developers to either manually search for specific translations and add a comment, or leave let the translators figure out how to find the best translation without context.
+
+
+## Why Fame?
+
+Fame solves the above mentioned issues to help developers and translators get the most out of tedious localization tasks.
+
+#### Integrated into Interface Builder
+
+Fame makes it easy for developers to specify which elements of your Storyboard and XIB files should be translated, all right within interface builder. Developers may also add a comment for each element to provide additional context to  translators.
+
+![Interface Builder Integration](docs/ib_detail.png)
+
+#### Command line interface
+
+Using the fame CLI, developers can export .strings files that only contain localizations for elements previously enabled in Interface Builder.
+
+![gif]()
+
+#### Generates beautiful .strings files
+
+Translators only receive the strings that should actually be translated, saving them time (and you potentially lots of money). All generated .strings files also contain each element's name and a useful comment to provide more context by the app developer.
+
+```css
+/* MyViewController.label.text: Explains how to purchase a pro subscription. */
+"Rfi-2u-xEd.text" = "Label";
+```
+
+## Installation
+
+Install the fame ruby gem using your terminal to get access to the fame command line interface.
+
+```bash
+$ gem install fame
+```
+
+#### Enable localization for Interface Builder files
+
+> **Note**: You may skip to the next section if you have already setup your project and Interface Builder files for localization.
+
+First off, add all supported languages to your project. This can be done by clicking the + button under your project's Localizations configuration. Go ahead and add as many languages as you want.
+
+![Add new language to project](docs/add_language.png)
+
+Next, make sure to enable localization for your Interface Builder files and choose the "Localizable Strings" option from the dropdown.
+
+![Add new language to project](docs/storyboard_setup.png)
+
+You should now have a Base Interface Builder file (e.g. `Main.storyboard`) in a `Base.lproj` folder and multiple localizable strings files (e.g. `Main.strings`) each within a language folder (e.g. `en.lproj` and `de.lproj`).
+
+![Add new language to project](docs/folder_structure.png)
+
+That's it, read on to enable fame for localization.
+
+#### Setup Fame for Interface Builder
+
+In order to enable the Interface Builder integration to specify the elements that should be translated, add the **[Fame.swift](platform/Fame.swift)** file to your Xcode project. To test the Interface Builder integration, open any Interface Builder file in your project, select an element (e.g. a UILabel) and you should see a new section that lets you configure localization for this element in the Attributes inspector.
+
+![Interface Builder Integration](docs/ib.png)
+
+You can now enable localization for each element you want to have translated.
+
+
+## Usage
+
+
+Once all localizable elements have been configured in Interface Builder, you can export the localizable .strings file using the `fame` command line tool.
+
+
+First, make sure to commit all local changes, just to be safe. Then open terminal, navigate to the root folder of your project and run
+
+
+```bash
+$ fame
+```
+
+In a nutshell, the fame command does the following:
+
+* Find all .storyboard and .xib files in the current folder (recursively, you can also pass a subpath or file to the fame command)
+* Lookup the localizable settings (you have set in Interface Builder) for each file
+* Generate the full localizable .strings file using Apple's `ibtool`
+* Filter the `ibtool` output based on your licalizable settings
+* Save a new `<NameOfStoryboardOrXIB>.strings` file to the `en.lproj` folder
+
+## Contributing
+
+1. Fork it ( https://github.com/aschuch/fame/fork )
+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
+
+#### TODO
+
+* Incremental updates of .string files (`ibtool --previous-file <OLD .storyboard> --incremental-file YY --localize-incremental`)
+* Write tests with fixtures
+
+## Contact
+
+Feel free to get in touch.
+
+* Website: <http://schuch.me>
+* Twitter: [@schuchalexander](http://twitter.com/schuchalexander)

data/bin/fame

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.push File.expand_path('../../lib', __FILE__)
+
+require 'rubygems'
+require 'commander'
+require 'colorize'
+require 'fame/version'
+require 'fame/interface_builder'
+
+#
+# The Fame CLI
+#
+class FameApplication
+  include Commander::Methods
+
+  def run
+    program :name, 'Fame'
+    program :version, Fame::VERSION
+    program :description, 'Replace identifiers within Apple Interface Builder files to use nice keys and descriptions for localization.'
+    default_command :localize
+
+    #
+    # Default localize command
+    #
+    command :localize do |c|
+      c.syntax = 'fame localize [options]'
+      c.description = 'Replaces generated identifiers of the given Interface Builder file(s) and generates .strings files.'
+      c.option '--path STRING', String, 'Path to an interface builder file or a folder that contains interface builder files.'
+
+      c.action do |args, options|
+        options.default :path => '.'
+
+        files = Fame::InterfaceBuilder.determine_ib_files!(options.path)
+        puts "\nFound #{files.count} files to localize.\n".light_black
+
+      	# Generate localizable strings for each file
+      	files.each_with_index do |f, index|
+          puts "(#{index+1}/#{files.count}) #{f}".light_blue
+
+      		ib = Fame::InterfaceBuilder.new
+
+      		# Generate new localizable.strings file
+      		strings = ib.generate_localizable_strings(f)
+
+          if strings.empty?
+      		  puts "✔".green + " (no strings to localize)︎".yellow
+          else
+            FileUtils.mkdir_p(strings_folder(f))
+            File.write(strings_file_path(f), strings)
+
+            puts "✔︎".green + " Generated strings file at #{strings_file_path(f)}".black
+          end
+
+          puts "-----------------------------------------------------\n".light_black
+      	end
+      end
+    end
+
+    run!
+  end
+
+  private
+
+  def strings_folder(path)
+    folder = File.dirname(path)
+    File.join(folder, "..", "en.lproj")
+  end
+
+  def strings_file_path(path)
+    file_name = File.basename(path, File.extname(path))
+    file = File.join(strings_folder(path), "#{file_name}.strings")
+    File.expand_path(file)
+  end
+
+end
+
+# run application
+FameApplication.new.run

data/lib/fame.rb

@@ -0,0 +1,5 @@
+require "fame/version"
+
+module Fame
+  # Your code goes here...
+end

data/lib/fame/interface_builder.rb

@@ -0,0 +1,139 @@
+require 'nokogiri' 		# to rewrite the storyboard
+require 'plist'				# to parse the localizable.plist file
+require 'colorize'		# colorful console output
+require_relative 'models'
+
+module Fame
+
+	class InterfaceBuilder
+		# Keypaths to custom runtime attributes (provided by iOS Extenstion, see Fame.swift)
+		LOCALIZATION_ENABLED_KEYPATH = "i18n_enabled".freeze
+		LOCALIZATION_COMMENT_KEYPATH = "i18n_comment".freeze
+
+		# All accepted Interface Builder file types
+		ACCEPTED_FILE_TYPES = [".storyboard", ".xib"].freeze
+
+		#
+		# Initialization
+		#
+		def self.determine_ib_files!(path = ".")
+			raise "The provided file or folder does not exist" unless File.exist? path
+
+			if File.directory?(path)
+				files = Dir.glob(path + "/**/*{#{ACCEPTED_FILE_TYPES.join(',')}}")
+				raise "The provided folder did not contain any interface files (#{ACCEPTED_FILE_TYPES.join(', ')})" unless files.count > 0
+				return files
+			else
+				raise "The provided file is not an interface file (#{ACCEPTED_FILE_TYPES.join(', ')})" unless ACCEPTED_FILE_TYPES.include? File.extname(path)
+				return [path]
+			end
+		end
+
+		#
+		# Generates a .strings file for the Interface Builder file at the given path.
+		# The output only contains elements where localization has been enabled.
+		#
+		def generate_localizable_strings(file)
+			localizable_strings_entries(file)
+				.sort_by! { |e| e.node.vc_name }
+				.map(&:formatted_strings_file_entry)
+				.join("\n\n")
+		end
+
+		private
+
+		#
+		# Generates ibtool output in plist format
+		#
+		def ibtool(file)
+			# 	<dict>
+			# 		<key>6lc-A3-0nG</key>
+			# 		<dict>
+			# 			<key>text</key>
+			# 			<string>Empty localization ID</string>
+			# 		</dict>
+			# 		...
+			# 	</dict>
+			output = `xcrun ibtool #{file} --localizable-strings --localizable-stringarrays`
+			plist = Plist::parse_xml(output)
+			strings = plist['com.apple.ibtool.document.localizable-strings']
+			string_arrays = plist['com.apple.ibtool.document.localizable-stringarrays']
+
+			[strings, string_arrays]
+		end
+
+		#
+		# Returns all XML nodes with a custom localization ID
+		#
+		def nodes(file)
+			storyboard = File.open(file)
+			doc = Nokogiri::XML(storyboard)
+
+			# Grab raw nokogiri nodes that have a localization keypath
+			raw_nodes = doc.xpath("//userDefinedRuntimeAttribute[@keyPath='#{LOCALIZATION_ENABLED_KEYPATH}']")
+
+			# Map raw nodes info to instances of LocalizedNode
+			raw_nodes.map do |node|
+				parent = node.parent.parent 													# i.e. UILabel, UISwitch, etc.
+				vc = parent.xpath("ancestor::viewController")					# the view controller of the element (only available in .storyboard files)
+				element_name = parent.name														# i.e. label, switch
+				original_id = parent['id'] 														# ugly Xcode ID, e.g. F4z-Kg-ni6
+				vc_name = vc.attr('customClass').value rescue nil			# name of custom view controller class
+
+				i18n_enabled = node.parent.xpath("userDefinedRuntimeAttribute[@keyPath='#{LOCALIZATION_ENABLED_KEYPATH}']").attr('value').value == "YES" rescue false
+				i18n_comment = node.parent.xpath("userDefinedRuntimeAttribute[@keyPath='#{LOCALIZATION_COMMENT_KEYPATH}']").attr('value').value rescue nil
+
+				LocalizedNode.new(node, original_id, vc_name, element_name, i18n_enabled, i18n_comment)
+			end
+		end
+
+		#
+		# Returns the localizable strings entries for a given
+		# Interface Builder file.
+		#
+		def localizable_strings_entries(file)
+			# Generate ibtool output
+			strings, string_arrays = ibtool(file)
+
+			# Get nodes for current file
+			nodes = nodes(file)
+
+			# Generate new strings file
+			entries = []
+			nodes.each do |node|
+				next unless node.i18n_enabled
+				unless element = strings[node.original_id] || string_arrays[node.original_id]
+					puts "  ✘ #{node.original_id} (#{node.element_name}): #{node.original_id} not found in ibtool output".red
+					next
+				end
+
+				# A localization may contain more than one element.
+				# e.g. a UITextField has a `text` and a `placeholdertext` localization
+				element.each do |property, value|
+					next if property == "ibExternalUserDefinedRuntimeAttributesLocalizableStrings"
+
+					if value.is_a?(Array)
+						# The localization contains an array of values, e.g. when localizing a UISegmentedControl
+						value.each_with_index do |v, index|
+							p = "#{property}[#{index}]"
+							entry = LocalizableStringsEntry.new(node, p, v)
+							entries << entry
+
+							puts "  ✔︎ #{entry.formatted_info}".green
+						end
+					else
+						# The localization only contains a single value
+						entry = LocalizableStringsEntry.new(node, property, value)
+						entries << entry
+
+						puts "  ✔︎ #{entry.formatted_info}".green
+					end
+
+				end
+			end
+
+			entries
+		end
+
+	end
+end

data/lib/fame/models.rb

@@ -0,0 +1,30 @@
+
+module Fame
+  
+  # nokogiri_node = original nokogiri node
+  # original_id = F4z-Kg-ni6
+  # vc_name = CustomViewController (optional)
+  # element_name = label
+  # i18n_enabled = true
+  # i18n_comment = "Best label ever invented"
+  LocalizedNode = Struct.new(:nokogiri_node, :original_id, :vc_name, :element_name, :i18n_enabled, :i18n_comment)
+
+  # node = LocalizedNode
+  # property = localizable element, e.g. text of a label
+  # value = localizable strings value (i.e. the translation)
+  LocalizableStringsEntry = Struct.new(:node, :property, :value) do
+
+    # The formatted .strings file entry
+    def formatted_strings_file_entry
+      comment = node.i18n_comment || "No comment provided by engineer."
+      key = "#{node.original_id}.#{property}"
+      ["/* #{formatted_info}: #{comment} */", "\"#{key}\" = \"#{value}\";"].join("\n")
+    end
+
+    # The formatted info of this entry
+    def formatted_info
+      [node.vc_name, node.element_name, property].compact.join(" ")
+    end
+  end
+
+end

data/lib/fame/version.rb

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

metadata

@@ -0,0 +1,156 @@
+--- !ruby/object:Gem::Specification
+name: fame
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Alexander Schuch
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-03-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: commander
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: plist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !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: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+description: Delightful localization of .storyboard and .xib files, right within Interface
+  Builder. Fame makes it easy to enable specific Interface Builder elements to be
+  translated and exported to localizable .strings files.
+email:
+- alexander@schuch.me
+executables:
+- fame
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/fame
+- lib/fame.rb
+- lib/fame/interface_builder.rb
+- lib/fame/models.rb
+- lib/fame/version.rb
+homepage: https://twitter.com/schuchalexander
+licenses:
+- MIT
+metadata: {}
+post_install_message: |-
+  Please add Fame.swift to your project to enable Interface Builder support.
+  -> https://github.com/aschuch/fame/blob/master/platform/Fame.swift
+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.2
+signing_key: 
+specification_version: 4
+summary: Delightful localization of .storyboard and .xib files, right within Interface
+  Builder.
+test_files: []
+has_rdoc: