Permalink
Browse files

Initial commit.

  • Loading branch information...
0 parents commit 72a39d875f8bf4a323f7f0e98456715172f6d318 @scelis scelis committed Feb 6, 2012
Showing with 1,019 additions and 0 deletions.
  1. +2 −0 Gemfile
  2. +30 −0 LICENSE
  3. +120 −0 README.md
  4. +3 −0 bin/twine
  5. +10 −0 lib/twine.rb
  6. +166 −0 lib/twine/cli.rb
  7. +9 −0 lib/twine/formatters.rb
  8. +58 −0 lib/twine/formatters/abstract.rb
  9. +94 −0 lib/twine/formatters/android.rb
  10. +79 −0 lib/twine/formatters/apple.rb
  11. +265 −0 lib/twine/runner.rb
  12. +151 −0 lib/twine/stringsfile.rb
  13. +3 −0 lib/twine/version.rb
  14. +3 −0 twine
  15. +26 −0 twine.gemspec
@@ -0,0 +1,2 @@
+source :rubygems
+gemspec
@@ -0,0 +1,30 @@
+Software License Agreement (BSD License)
+
+Copyright (c) 2012, Mobiata, LLC
+All rights reserved.
+
+Redistribution and use of this software in source and binary forms, with or
+without modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+* Neither the name of the organization nor the names of its contributors may be
+ used to endorse or promote products derived from this software without
+ specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,120 @@
+# Twine
+
+Twine is a command line tool for managing your strings and their translations. These strings are all stored in a master text file and then Twine uses this file to import and export strings in a variety of file types, including iOS and Mac OS X `.strings` files as well as Android `.xml` files. This allows individuals and companies to easily share strings across multiple projects, as well as export strings in any format the user wants.
+
+## Install
+
+### As a Gem
+
+Twine is most easily installed as a Gem.
+
+ sudo gem install twine
+
+### From Source
+
+You can also run Twine directly from source. However, it requires [rubyzip][rubyzip] in order to create and read standard zip files.
+
+ sudo gem install rubyzip
+ git clone git://github.com/mobiata/twine.git
+ cd twine
+ ./twine --help
+
+Make sure you run the `twine` executable at the root of the project as it properly sets up your Ruby library path. The `bin/twine` executable does not.
+
+## String File Format
+
+Twine stores all of its strings in a single file. The format of this file is a slight variant of the [Git][git] config file format, which itself is based on the old [Windows INI file][INI] format. The entire file is broken up into sections, which are created by placing the section name between two pairs of square brackets. Sections are optional, but they are a recommended way of breaking your strings into smaller, more manageable chunks.
+
+Each grouping section contains N string definitions. These string definitions start with the string key placed within a single pair of square brackets. This string definition then contains a number of key-value pairs, including a comment, a comma-separated list of tags (which are used by Twine to select a subset of strings), and all of the translations.
+
+### Tags
+
+Tags are used by Twine as a way to only work with a subset of your strings at any given point in time. Each string can be assigned zero or more tags which are separated by commas. When a string has no tags, that string will never be selected by Twine. You can get a list of all strings currently missing tags by executing the `generate-report` command.
+
+### Whitespace
+
+Whitepace in this file is mostly ignored. If you absolutely need to put spaces at the beginning or end of your translated string, you can wrap the entire string in a pair of `` ` `` characters. If your actual string needs to start *and* end with a grave accent, you can wrap it in another pair of `` ` `` characters. See the example, below.
+
+### Example
+
+ [[General]]
+ [yes]
+ en = Yes
+ es = Sí
+ fr = Oui
+ ja = はい
+ [no]
+ en = No
+ fr = Non
+ ja = いいえ
+
+ [[Errors]]
+ [path_not_found_error]
+ en = The file '%@' could not be found.
+ tags = app1,app6
+ comment = An error describing when a path on the filesystem could not be found.
+ [network_unavailable_error]
+ en = The network is currently unavailable.
+ tags = app1
+ comment = An error describing when the device can not connect to the internet.
+
+ [[Escaping Example]]
+ [list_item_separator]
+ en = `, `
+ tags = mytag
+ comment = A string that should be placed between multiple items in a list. For example: Red, Green, Blue
+ [grave_accent_quoted_string]
+ en = ``%@``
+ tags = myothertag
+ comment = This string will evaluate to `%@`.
+
+## Usage
+
+ Usage: twine COMMAND STRINGS_FILE [INPUT_OR_OUTPUT_PATH] [--lang LANG1,LANG2...] [--tag TAG1,TAG2,TAG3...] [--format FORMAT]
+
+### Commands
+
+#### `generate-string-file`
+
+This command creates an Apple or Android strings file from the master strings data file.
+
+ > twine generate-string-file /path/to/strings.txt values-ja.xml --tag common,app1
+ > twine generate-string-file /path/to/strings.txt Localizable.strings --lang ja --tag mytag
+ > twine generate-string-file /path/to/strings.txt all-english.strings --lang en
+
+#### `generate-all-string-files`
+
+This command is a convenient way to call `generate-string-file` multiple times. It uses standard Mac OS X, iOS, and Android conventions to figure out exactly which files to create given a parent directory. For example, if you point it to a parent directory containing `en.lproj`, `fr.lproj`, and `ja.lproj` subdirectories, Twine will create a `Localizable.strings` file of the appropriate language in each of them. This is often the command you will want to execute during the build phase of your project.
+
+ > twine generate-all-string-files /path/to/strings.txt /path/to/project/locales/directory --tag common,app1
+
+#### `consume-string-file`
+
+This command slurps all of the strings from a `.strings` or `.xml` file and incorporates the translated text into the master strings data file. This is a simple way to incorporate any changes made to a single file by one of your translators. It will only identify strings that already exist in the master data file.
+
+ > twine consume-string-file /path/to/strings.txt fr.strings
+ > twine consume-string-file /path/to/strings.txt Localizable.strings --lang ja
+ > twine consume-string-file /path/to/strings.txt es.xml
+
+#### `generate-loc-drop`
+
+This command is a convenient way to generate a zip file containing files created by the `generate-string-file` command. It is often used for creating a single zip containing a large number of strings in all languages which you can then hand off to your translation team.
+
+ > twine generate-loc-drop /path/to/strings.txt LocDrop1.zip
+ > twine generate-loc-drop /path/to/strings.txt LocDrop2.zip --lang en,fr,ja,ko --tag common,app1
+
+#### `consume-loc-drop`
+
+This command is a convenient way of taking a zip file and executing the `consume-string-file` command on each file within the archive. It is most often used to incorporate all of the changes made by the translation team after they have completed work on a localization drop.
+
+ > twine consume-loc-drop /path/to/strings.txt LocDrop2.zip
+
+#### `generate-report`
+
+This command gives you useful information about your strings. It will tell you how many strings you have, how many have been translated into each language, and whether your master strings data file has any duplicate string keys.
+
+ > twine generate-report /path/to/strings.txt
+
+[rubyzip]: http://rubygems.org/gems/rubyzip
+[git]: http://git-scm.org/
+[INI]: http://en.wikipedia.org/wiki/INI_file
@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'twine'
+Twine::Runner.run(ARGV)
@@ -0,0 +1,10 @@
+module Twine
+ class Error < StandardError
+ end
+
+ require 'twine/cli'
+ require 'twine/formatters'
+ require 'twine/runner'
+ require 'twine/stringsfile'
+ require 'twine/version'
+end
@@ -0,0 +1,166 @@
+require 'optparse'
+
+module Twine
+ class CLI
+ def initialize(args, options)
+ @options = options
+ @args = args
+ end
+
+ def self.parse_args(args, options)
+ new(args, options).parse_args
+ end
+
+ def parse_args
+ parser = OptionParser.new(@args) do |opts|
+ opts.banner = 'Usage: twine COMMAND STRINGS_FILE [INPUT_OR_OUTPUT_PATH] [--lang LANG1,LANG2...] [--tag TAG1,TAG2,TAG3...] [--format FORMAT]'
+ opts.separator ''
+ opts.separator 'The purpose of this script is to convert back and forth between multiple data formats, allowing us to treat our strings (and translations) as data stored in a text file. We can then use the data file to create drops for the localization team, consume similar drops returned by the localization team, generate reports on the strings, as well as create iOS and Android string files to ship with our products.'
+ opts.separator ''
+ opts.separator 'Commands:'
+ opts.separator ''
+ opts.separator 'generate-strings-file -- Generates a string file in a certain LANGUAGE given a particular FORMAT. This script will attempt to guess both the language and the format given the filename and extension. For example, "ko.xml" will generate a Korean language file for Android.'
+ opts.separator ''
+ opts.separator 'generate-all-string-files -- Generates all the string files necessary for a given project. The parent directory to all of the locale-specific directories in your project should be specified as the INPUT_OR_OUTPUT_PATH. This command will most often be executed by your build script so that each build always contains the most recent strings.'
+ opts.separator ''
+ opts.separator 'consume-string-file -- Slurps all of the strings from a translated strings file into the specified STRINGS_FILE. If you have some files returned to you by your translators you can use this command to incorporate all of their changes. This script will attempt to guess both the language and the format given the filename and extension. For example, "ja.strings" will assume that the file is a Japanese iOS strings file.'
+ opts.separator ''
+ opts.separator 'generate-loc-drop -- Generates a zip archive of strings files in any format. The purpose of this command is to create a very simple archive that can be handed off to a translation team. The translation team can unzip the archive, translate all of the strings in the archived files, zip everything back up, and then hand that final archive back to be consumed by the consume-loc-drop command.'
+ opts.separator ''
+ opts.separator 'consume-loc-drop -- Consumes an archive of translated files. This archive should be in the same format as the one created by the generate-loc-drop command.'
+ opts.separator ''
+ opts.separator 'generate-report -- Generates a report containing data about your strings. For example, it will tell you if you have any duplicate strings or if any of your strings are missing tags. In addition, it will tell you how many strings you have and how many of those strings have been translated into each language.'
+ opts.separator ''
+ opts.separator 'General Options:'
+ opts.separator ''
+ opts.on('-l', '--lang LANGUAGES', Array, 'The language code(s) to use for the specified action.') do |langs|
+ @options[:languages] = langs
+ end
+ opts.on('-t', '--tag TAGS', Array, 'The tag(s) to use for the specified action. Only strings with that tag will be processed.') do |tags|
+ @options[:tags] = tags
+ end
+ opts.on('-f', '--format FORMAT', 'The file format to read or write (iOS, Android). Additional formatters can be placed in the formats/ directory.') do |format|
+ lformat = format.downcase
+ found_format = false
+ Formatters::FORMATTERS.each do |formatter|
+ if formatter::FORMAT_NAME == lformat
+ found_format = true
+ break
+ end
+ end
+ if !found_format
+ puts "Invalid format: #{format}"
+ end
+ @options[:format] = lformat
+ end
+ opts.on('-h', '--help', 'Show this message.') do |h|
+ puts opts.help
+ exit
+ end
+ opts.on('--version', 'Print the version number and exit.') do |x|
+ puts "Twine version #{Twine::VERSION}"
+ exit
+ end
+ opts.separator ''
+ opts.separator 'Examples:'
+ opts.separator ''
+ opts.separator '> twine generate-string-file strings.txt ko.xml --tag FT'
+ opts.separator '> twine generate-all-string-files strings.txt Resources/Locales/ --tag FT,FB'
+ opts.separator '> twine consume-string-file strings.txt ja.strings'
+ opts.separator '> twine generate-loc-drop strings.txt LocDrop5.zip --tag FT,FB --format android --lang de,en,en-GB,ja,ko'
+ opts.separator '> twine consume-loc-drop strings.txt LocDrop5.zip'
+ opts.separator '> twine generate-report strings.txt'
+ end
+ parser.parse!
+
+ if @args.length == 0
+ puts parser.help
+ exit
+ end
+
+ @options[:command] = @args[0]
+
+ if !VALID_COMMANDS.include? @options[:command]
+ puts "Invalid command: #{@options[:command]}"
+ exit
+ end
+
+ if @args.length == 1
+ puts 'You must specify your strings file.'
+ exit
+ end
+
+ @options[:strings_file] = @args[1]
+
+ case @options[:command]
+ when 'generate-string-file'
+ if @args.length == 3
+ @options[:output_path] = @args[2]
+ elsif @args.length > 3
+ puts "Unknown argument: #{@args[3]}"
+ exit
+ else
+ puts 'Not enough arguments.'
+ exit
+ end
+ if @options[:languages] and @options[:languages].length > 1
+ puts 'Please only specify a single language for the generate-string-file command.'
+ exit
+ end
+ when 'generate-all-string-files'
+ if ARGV.length == 3
+ @options[:output_path] = @args[2]
+ elsif @args.length > 3
+ puts "Unknown argument: #{@args[3]}"
+ exit
+ else
+ puts 'Not enough arguments.'
+ exit
+ end
+ when 'consume-string-file'
+ if @args.length == 3
+ @options[:input_path] = @args[2]
+ elsif @args.length > 3
+ puts "Unknown argument: #{@args[3]}"
+ exit
+ else
+ puts 'Not enough arguments.'
+ exit
+ end
+ if @options[:languages] and @options[:languages].length > 1
+ puts 'Please only specify a single language for the consume-string-file command.'
+ exit
+ end
+ when 'generate-loc-drop'
+ if @args.length == 3
+ @options[:output_path] = @args[2]
+ elsif @args.length > 3
+ puts "Unknown argument: #{@args[3]}"
+ exit
+ else
+ puts 'Not enough arguments.'
+ exit
+ end
+ if !@options[:format]
+ puts 'You must specify a format.'
+ exit
+ end
+ when 'consume-loc-drop'
+ if @args.length == 3
+ @options[:input_path] = @args[2]
+ elsif @args.length > 3
+ puts "Unknown argument: #{@args[3]}"
+ exit
+ else
+ puts 'Not enough arguments.'
+ exit
+ end
+ when 'generate-report'
+ if @args.length > 2
+ puts "Unknown argument: #{@args[2]}"
+ exit
+ end
+ end
+ end
+ end
+end
@@ -0,0 +1,9 @@
+require 'twine/formatters/abstract'
+require 'twine/formatters/android'
+require 'twine/formatters/apple'
+
+module Twine
+ module Formatters
+ FORMATTERS = [Formatters::Apple, Formatters::Android]
+ end
+end
Oops, something went wrong.

0 comments on commit 72a39d8

Please sign in to comment.