(CODEMGMT-725) Externalize error message strings

This commit adds the ruby i18n libraries and externalizes all
error messages that the gem throws. When adding or changing
translation, the command `bundle exec rake gettext:pot`
must be run in order to create 'locales/semantic_puppet.pot'

Previously the gemspec required 'semantic_puppet', but that file
had to be changed to include the gettext functionality. This caused
an error when running any bundle command. The solution is to move the
information that the gemspec needs (the version number) into a separate
file (gem_version.rb) and include only that file.

Author: austb

.gitignore

@@ -6,3 +6,4 @@ doc
 .idea/
 /.project
 Gemfile.lock
+locales/semantic_puppet.pot

README.md

@@ -57,6 +57,26 @@ publishing modules to [Puppet Forge](https://forge.puppetlabs.com) which is
 documented at 
 [Publishing Modules on the Puppet Forge](https://docs.puppetlabs.com/puppet/latest/reference/modules_publishing.html#dependencies-in-metadatajson).
 
+### i18n
+
+When adding new error or log messages please follow the instructions for
+[writing translatable code](https://github.com/puppetlabs/gettext-setup-gem#writing-translatable-code).
+
+The SemanticPuppet gem will default to outputing all error messages in English, but you may set the locale
+using the `FastGettext.set_locale` method. If translations do not exist for the language you request then the gem will
+default to English. The `set_locale` method will return the locale, as a string, that FastGettext will now
+use to report PuppetForge errors.
+
+``` ruby
+# Assuming the German translations exist, this will set the reporting language
+# to German
+
+locale = FastGettext.set_locale "de_DE"
+
+# If it successfully finds Germany's locale, locale will be "de_DE"
+# If it fails to find any German locale, locale will be "en"
+```
+
 Contributors
 ------------
 

Rakefile

@@ -56,3 +56,12 @@ begin
 rescue LoadError
   warn "[Warning]: Could not load `bundler/gem_tasks`."
 end
+
+# Gettext tasks
+begin
+  spec = Gem::Specification.find_by_name 'gettext-setup'
+  load "#{spec.gem_dir}/lib/tasks/gettext.rake"
+  GettextSetup.initialize(File.absolute_path('locales', File.dirname(__FILE__)))
+rescue LoadError
+  warn "[Warning]: Could not load gettext tasks."
+end

lib/semantic_puppet.rb

@@ -1,7 +1,9 @@
+require 'gettext-setup'
+
 module SemanticPuppet
+  GettextSetup.initialize(File.absolute_path('../locales', File.dirname(__FILE__)))
+
   autoload :Version, 'semantic_puppet/version'
   autoload :VersionRange, 'semantic_puppet/version_range'
   autoload :Dependency, 'semantic_puppet/dependency'
-
-  VERSION = '0.1.3'
 end

lib/semantic_puppet/gem_version.rb

@@ -0,0 +1,3 @@
+module SemanticPuppet
+  VERSION = '0.1.3'
+end

lib/semantic_puppet/version.rb

@@ -18,15 +18,15 @@ def parse(ver)
         match, major, minor, patch, prerelease, build = *ver.match(/\A#{REGEX_FULL}\Z/)
 
         if match.nil?
-          raise "Unable to parse '#{ver}' as a semantic version identifier"
+          raise _("Unable to parse '%{version}' as a semantic version identifier") % {version: ver}
         end
 
         prerelease = parse_prerelease(prerelease) if prerelease
         # Build metadata is not yet supported in semantic_puppet, but we hope to.
         # The following code prevents build metadata for now.
         #build = parse_build_metadata(build) if build
         if !build.nil?
-          raise "'#{ver}' MUST NOT include build identifiers"
+          raise _("'%{version}' MUST NOT include build identifiers") % {version: ver}
         end
 
         self.new(major.to_i, minor.to_i, patch.to_i, prerelease, build)
@@ -46,11 +46,11 @@ def parse_prerelease(prerelease)
         prerelease = prerelease.split('.', -1)
 
         if prerelease.empty? or prerelease.any? { |x| x.empty? }
-          raise "#{subject} MUST NOT be empty"
+          raise _("%{subject} MUST NOT be empty") % {subject: subject}
         elsif prerelease.any? { |x| x =~ /[^0-9a-zA-Z-]/ }
-          raise "#{subject} MUST use only ASCII alphanumerics and hyphens"
+          raise _("%{subject} MUST use only ASCII alphanumerics and hyphens") % {subject: subject}
         elsif prerelease.any? { |x| x =~ /^0\d+$/ }
-          raise "#{subject} MUST NOT contain leading zeroes"
+          raise _("%{subject} MUST NOT contain leading zeroes") % {subject: subject}
         end
 
         return prerelease.map { |x| x =~ /^\d+$/ ? x.to_i : x }
@@ -61,9 +61,9 @@ def parse_build_metadata(build)
         build = build.split('.', -1)
 
         if build.empty? or build.any? { |x| x.empty? }
-          raise "#{subject} MUST NOT be empty"
+          raise _("%{subject} MUST NOT be empty") % {subject: subject}
         elsif build.any? { |x| x =~ /[^0-9a-zA-Z-]/ }
-          raise "#{subject} MUST use only ASCII alphanumerics and hyphens"
+          raise _("%{subject} MUST use only ASCII alphanumerics and hyphens") % {subject: subject}
         end
 
         return build

lib/semantic_puppet/version_range.rb

@@ -46,7 +46,7 @@ def parse(range_str)
         end
 
       rescue ArgumentError
-        raise ArgumentError, "Unparsable version range: #{range_str.inspect}"
+        raise ArgumentError, _("Unparsable version range: %{range}") % {range: range_str.inspect}
       end
 
       private

locales/config.yaml

@@ -0,0 +1,21 @@
+---
+# This is the project-specific configuration file for setting up
+# fast_gettext for your project.
+gettext:
+  # This is used for the name of the .pot and .po files; they will be
+  # called <project_name>.pot?
+  project_name: 'semantic_puppet'
+  # This is used in comments in the .pot and .po files to indicate what
+  # project the files belong to and should bea little more desctiptive than
+  # <project_name>
+  package_name: Semantic Puppet Gem
+  # The locale that the default messages in the .pot file are in
+  default_locale: en
+  # The email used for sending bug reports.
+  bugs_address: [email protected]
+  # The holder of the copyright.
+  copyright_holder: Puppet, Inc.
+  # Patterns for +Dir.glob+ used to find all files that might contain
+  # translatable content, relative to the project root directory
+  source_files:
+    - 'lib/**/*.rb'

semantic_puppet.gemspec

@@ -1,6 +1,6 @@
 # -*- encoding: utf-8 -*-
 $:.push File.expand_path("../lib", __FILE__)
-require "semantic_puppet"
+require "semantic_puppet/gem_version"
 
 spec = Gem::Specification.new do |s|
   # Metadata
@@ -22,6 +22,8 @@ spec = Gem::Specification.new do |s|
   # Dependencies
   s.required_ruby_version = '>= 1.8.7'
 
+  s.add_dependency "gettext-setup", ">= 0.3"
+
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
   s.add_development_dependency "simplecov"