i18n_flow 0.1.0

data/doc/tags.md

@@ -0,0 +1,488 @@
+Tags
+====
+
+!only
+-----
+
+With `!only`, you can explicitly claim that a key *may* not exist on both files.  
+Linter won't complain even if a key *does* exist. If you don't prefer this behavior, use stricter `!only:LOCALES`.
+
+It comes in handy when you have texts that don't need to be translated into another language, still want to manage in a locale file.
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>👎</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  
+```
+
+</td></tr><tr><td colspan=3>
+
+Missing `ja.desc`
+
+</td></tr></tbody></table>
+
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: !only 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about `ja.desc` even if it doesn't exist
+
+</td></tr></tbody></table>
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: !only 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about `ja.desc` even if it does exist
+
+</td></tr></tbody></table>
+
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>👎</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+Having the extra `ja.desc`
+
+</td></tr></tbody></table>
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: !only '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about `ja.desc`
+
+</td></tr></tbody></table>
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: !only '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about `ja.desc`
+
+</td></tr></tbody></table>
+
+
+!only:LOCALES
+-------------
+
+It's similar to `!only`, but is stricter.  
+It can take comma-separated locales as a parameter just like `!only:en` or `!only:en,ja,zh-HK`, and ensures that a key only exists in files of the specified locales.
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>👎</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: !only:en 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter will complain about `ja.desc`, because the key is supposed to exist only in `en`.
+
+</td></tr></tbody></table>
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>👎</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: !only:ja '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter will complain about `en.desc`, because the key is supposed to exist only in `ja`.
+
+</td></tr></tbody></table>
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: !only:en,ja 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+The key can exist in the specified locales `en,ja`
+
+</td></tr></tbody></table>
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  desc: !only:en,ja 'A situation in...'
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  
+```
+
+</td></tr><tr><td colspan=3>
+
+Note that it doesn't mean to ensure existance of the key.
+
+</td></tr></tbody></table>
+
+
+!ignore:key
+-----------
+
+With `!ignore:key`, you can suppress any error on a certain key.
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  title: 'Non zero sum'
+  
+```
+
+</td><td>
+
+```yaml
+ja:
+  title: '非ゼロ和'
+  desc: !ignore:key '複数の人が相互...'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about an asymmetric key
+
+</td></tr></tbody></table>
+
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  follower_count:
+    one: '1 follower'
+    other: '%{count} followers'
+```
+
+</td><td>
+
+```yaml
+ja:
+  follower_count: !ignore:key '%{count} フォロワ'
+  
+  
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about a structural mismatch
+
+</td></tr></tbody></table>
+
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  key: !ignore:key '%{alpha}'
+```
+
+</td><td>
+
+```yaml
+ja:
+  key: '%{gamma}'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about a difference in interpolation arguments
+
+</td></tr></tbody></table>
+
+
+!ignore:args
+------------
+
+With `!ignore:args`, you can suppress an error of asymmetric interpolation arguments.
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  key: '%{alpha}'
+```
+
+</td><td>
+
+```yaml
+ja:
+  key: !ignore:args '%{gamma}'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter won't complain about a difference in interpolation arguments
+
+</td></tr></tbody></table>
+
+
+!todo
+-----
+
+With `!todo`, you can annotate that a key needs to be translated in the future.  
+It can be only annotated on scalar values, mappings and sequences are not accepted.
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>✅</th><td>
+
+```yaml
+en:
+  follower_count:
+    one: '1 follower'
+    other: '%{count} followers'
+```
+
+</td><td>
+
+```yaml
+ja:
+  follower_count:
+    one: !todo '1 follower'
+    other: !todo '%{count} followers'
+```
+
+</td></tr><tr><td colspan=3>
+
+Two keys need to be translated
+
+</td></tr></tbody></table>
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>👎</th><td>
+
+```yaml
+en:
+  follower_count:
+    one: '1 follower'
+    other: '%{count} followers'
+```
+
+</td><td>
+
+```yaml
+ja:
+  follower_count: !todo
+    one: '1 follower'
+    other: '%{count} followers'
+```
+
+</td></tr><tr><td colspan=3>
+
+You can't annotate on a mapping or a sequence.
+
+</td></tr></tbody></table>
+
+
+<table><thead><tr>
+  <th></th>
+  <th>master</th>
+  <th>foreign</th>
+</tr></thead><tbody><tr><th>👎</th><td>
+
+```yaml
+en:
+  follower_count:
+    one: 'a follower'
+    other: '%{count} followers'
+```
+
+</td><td>
+
+```yaml
+ja:
+  follower_count:
+    one: !todo '1 follower'
+    other: !todo '%{count} followers'
+```
+
+</td></tr><tr><td colspan=3>
+
+Linter will complain `ja.follower_count.one` has different content.  
+This usually indicates that there has been updates on the master file, or that it has been translated but forgotten to remove `!todo`.
+
+</td></tr></tbody></table>

data/example/example.en.yml

@@ -0,0 +1,14 @@
+en:
+  example:
+    title: 'Example'
+
+    # Use first name in English
+    greeting: 'Hello %{first_name},'
+
+    # Might be hard to translate into other langs
+    serendipity: 'serendipity'
+
+    # Only available in English version
+    follower_count: !only:en
+      one: '1 follower'
+      other: '%{count} followers'

data/example/example.ja.yml

@@ -0,0 +1,9 @@
+ja:
+  example:
+    title: 'サンプル'
+
+    # Use last name in Japanese
+    greeting: !ignore:args 'こんにちは %{last_name}さん'
+
+    # Should translate later
+    serendipity: !todo 'serendipity'

data/exe/i18n_flow

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+# enable local usage from cloned repo
+root = File.expand_path('../..', __FILE__)
+$LOAD_PATH << "#{root}/lib" if File.exist?("#{root}/Gemfile")
+
+require 'i18n_flow'
+require 'i18n_flow/cli'
+
+I18nFlow.config.auto_configure!
+I18nFlow::CLI.new(ARGV).run

data/i18n_flow.gemspec

@@ -0,0 +1,28 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'i18n_flow/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'i18n_flow'
+  spec.version       = I18nFlow::VERSION
+  spec.authors       = ['Yuki Iwanaga']
+  spec.email         = ['yuki@creasty.com']
+
+  spec.summary       = %q{Manage translation status in yaml file}
+  spec.description   = %q{Manage translation status in yaml file}
+  spec.homepage      = 'https://github.com/creasty/i18n_flow'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'psych', '>= 3.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.7'
+  spec.add_development_dependency 'fakefs'
+  spec.add_development_dependency 'pry'
+end

data/i18n_flow.yml

@@ -0,0 +1,8 @@
+base_path: example
+glob_patterns:
+  - '**/*.yml'
+valid_locales:
+  - en
+  - ja
+locale_pairs:
+  - ['en', 'ja']

data/lib/i18n_flow/cli/color.rb

@@ -0,0 +1,18 @@
+class I18nFlow::CLI
+  module Color
+    COLORS = {
+      black:   30,
+      red:     31,
+      green:   32,
+      yellow:  33,
+      blue:    34,
+      magenta: 35,
+      cyan:    36,
+      white:   37,
+    }.freeze
+
+    def color(str, c)
+      "\e[1;#{COLORS[c]}m#{str}\e[0m"
+    end
+  end
+end

data/lib/i18n_flow/cli/command_base.rb

@@ -0,0 +1,33 @@
+require_relative '../util'
+
+class I18nFlow::CLI
+  class CommandBase
+    attr_reader(*%i[
+      args
+      options
+    ])
+
+    def initialize(args)
+      @args    = args.dup
+      @options = I18nFlow::Util::parse_options(@args)
+    end
+
+    def invoke!
+      raise 'Not implemented'
+    end
+
+    def exit_with_message(status, *args)
+      if status.zero?
+        puts(*args)
+      else
+        $stderr.puts(*args)
+      end
+
+      exit status
+    end
+
+    def color_enabled?
+      options['nocolor'].nil?
+    end
+  end
+end

data/lib/i18n_flow/cli/copy_command.rb

@@ -0,0 +1,69 @@
+require 'psych'
+require_relative 'command_base'
+require_relative '../util'
+require_relative '../parser'
+
+class I18nFlow::CLI
+  class CopyCommand < CommandBase
+    def invoke!
+      unless src_file && dst_file
+        exit_with_message(1, 'usage: i18n_flow copy [--locale=LOCALE] SRC_FILE DST_FILE')
+      end
+
+      parser.parse!
+
+      mark_as_todo(parser.root_proxy)
+
+      if locale && first_key_node
+        first_key_node.value = locale
+      end
+
+      File.write(dst_file, parser.root_proxy.to_yaml)
+    end
+
+    def src_file
+      args[0]
+    end
+
+    def dst_file
+      args[1]
+    end
+
+    def locale
+      options['locale']
+    end
+
+    def first_key_node
+      return @first_key_node if defined?(@first_key_node)
+      @first_key_node = parser.root_proxy
+        .send(:indexed_object)
+        .node
+        .tap { |n| break unless n.is_a?(Psych::Nodes::Mapping) }
+        &.tap { |n| break n.children.first }
+    end
+
+  private
+
+    def parser
+      @parser ||= I18nFlow::Parser.new(File.read(src_file), file_path: src_file)
+    end
+
+    def mark_as_todo(ast)
+      if ast.alias?
+        return
+      end
+      if ast.scalar?
+        ast.node.tag = '!todo'
+
+        # https://github.com/ruby/psych/blob/f30b65befa4f0a5a8548d482424a84a2383b0284/ext/psych/yaml/emitter.c#L1187
+        ast.node.plain = ast.node.quoted = false
+
+        return
+      end
+
+      ast.each do |k, v|
+        mark_as_todo(v)
+      end
+    end
+  end
+end

data/lib/i18n_flow/cli/help_command.rb

@@ -0,0 +1,29 @@
+require_relative 'command_base'
+
+class I18nFlow::CLI
+  class HelpCommand < CommandBase
+    TEXT = <<-HELP
+Manage translation status in yaml file
+
+Usage:
+    i18n_flow COMMAND [args...]
+    i18n_flow [options]
+
+Options:
+    -v, --version    Show version
+    -h               Show help
+
+Commands:
+    lint       Validate files
+    search     Search contents and keys
+    copy       Copy translations and mark as todo
+    split      Split a file into proper-sized files
+    version    Show version
+    help       Show help
+    HELP
+
+    def invoke!
+      puts TEXT
+    end
+  end
+end