gettext-setup 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8cb929527d234a142edba900b86ff9b1e2a8543d
+  data.tar.gz: cdb14138a6bcc08bad38ac0acf373a3e53f36e97
+SHA512:
+  metadata.gz: eb0462b300efe1a2e63239f849e4cc3cc228ea03faed2747570dac0cec5107c85999115dd21e6445ca36b39a4bb81069cdb63ac79a578d0757bc143d6fb84299
+  data.tar.gz: 733995b80a2dd5865746ec4e2d48bf8a7b0071b6d04686df69938e753763deed50ce74388c13e793f2acab1c71fa964cdf9e4410842aabcc72ba7d41e724be55

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gem 'fast_gettext'
+
+gem 'rake', :require => false
+
+group :development do
+  gem 'gettext', ">= 3.0.2"
+end

data/Gemfile.lock

@@ -0,0 +1,18 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    fast_gettext (1.0.0)
+    gettext (3.2.1)
+      locale (>= 2.0.5)
+      text (>= 1.3.0)
+    locale (2.1.2)
+    rake (10.4.2)
+    text (1.3.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  fast_gettext
+  gettext (>= 3.0.2)
+  rake

data/LICENSE

@@ -0,0 +1,17 @@
+   gettext-setup gem
+
+   Copyright (C) 2016 Puppet, Inc.
+
+   Puppet, Inc. can be contacted at: info@puppet.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,105 @@
+# gettext-setup gem
+
+This is a simple gem to set up i18n for Ruby projects (including [Sinatra](www.sinatrarb.com/) web apps) using gettext and fast gettext.
+
+This project sets the default locale to English. If the user has set a different locale in their browser preferences, and we support the user's preferred locale, strings and data formatting will be customized for that locale.
+
+## Terminology
+
+**Translatable strings** - User-facing strings that are in scope for i18n (see the in scope/out of scope sections [here](https://confluence.puppetlabs.com/display/ENG/i18n#i18n-TasksandMilestones)).
+
+**POT file** - Portable Objects Template. This is the file that stores externalized English strings. It includes the source file and line number of the string.
+
+**PO file** - A bilingual file containing the source English strings (msgid) and target language strings (msgstr). This file is generated from the POT file and is where translated strings are added. A PO file is generated for each language.
+
+**Transifex** - A translation management system. When PO files are updated, the updates are pulled into Transifex and translated there.
+
+## Setup for your project
+
+These are the poingant bits of this example that you need to replicate in
+your project:
+
+1. Add `gem 'gettext-setup'` to your `Gemfile`.
+1. Add `gem 'fast_gettext'` to your `Gemfile`. This line is only needed
+   for running the bundled `rake` task.
+1. Copy `locales/config-sample.yaml` to your project and put it into a
+`locales` directory as `config.yaml`.
+1. Edit `locales/config.yaml` and make the necessary changes for your
+   project
+1. Add these three lines to your `Rakefile`:
+```
+    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__)))
+```
+1. Add this line to the top of your `app.rb`:
+    `require 'gettext-setup'`
+1. Add these lines inside the class declared in your `app.rb`:
+```
+    include FastGettext::Translation
+    GettextSetup.initialize(File.absolute_path('locales', File.dirname(__FILE__)))
+    before do
+      FastGettext.locale = GettextSetup.negotiate_locale(env["HTTP_ACCEPT_LANGUAGE"])
+    end
+```
+
+## Writing translatable code
+
+### Use full sentences
+Write user-facing strings as full sentences rather than joining multiple strings to form a full sentence because the word order in other languages can be different to English. See [Tips on writing translation-friendly strings](https://confluence.puppetlabs.com/display/ENG/Tips+for+writing+translation-friendly+strings).
+
+### Use the translation function _()
+Wrap user-facing strings in the `_()` function so they can be externalized to a POT file.
+
+E.g.  `_("Hello, world!")`
+
+### Interpolation
+To add dynamic data to a string, use the following string formatting and translation function:
+
+`_("We negotiated a locale of %{locale}") % {locale: FastGettext.locale}`
+
+### Pluralize with the n_() function
+
+Wrap strings that include pluralization with the `n_()` function.
+
+E.g. `n_("There is %{count} bicycle in %{city}", "There are %{count} bicycles in %{city}", num_bikes) % {count: num_bikes, city: "Beijing"},`
+
+Pluralization rules vary across languages. The pluralization rules are specified in the PO file and look something like this `Plural-Forms: nplurals=2; plural=(n > 1);`. This is the pluralization rule for German. It means that German has two pluralization rules. The first rule is `plural=n > 1)` and the second rule is all other counts.
+
+Plurals are selected from the PO file by index. Here's an example of how a
+pluralized string is handled in a PO file:
+
+`msgid "%{count} file"
+`msgid_plural "%{count} files"
+`msgstr[0] "%{count} Dateien"
+`msgstr[1] "%{count} Datei"
+
+The `msgid` is the singular version of the English source string that's pulled in to the POT file and PO from the code file.
+
+The `msgid_plural` is the plural version of the English source string.
+
+The two `msgstr` lines show that German has two rules for pluralization. The indices map to the `Plural-Forms: nplurals=2; plural=(n > 1);` rule that we specified in the PO file. The `[0]` index represents `plural=(n > 1)` and the `[1]` index represents all other pluralization cases (in other words, when the count equals 0 or 1).
+
+### Comments
+To provide translators with some contextual information or instructions about a string, precede the string with a comment. Start the comment with "TRANSLATOR: " to make it obvious that you are providing instructions for the translator. The comment gets pulled in to the POT file and will show up as a comment in Transifex.
+
+E.g. `# TRANSLATOR: The placeholder in this string represents the name of a parameter.`
+
+## Translation workflow
+
+1. Wrap the translation function around translatable strings in code files
+
+2. Run `rake gettext:pot` to parse the source code and extract translatable strings into the message catalog in `locales/<project_name>.pot`. If a POT file already exists, this rake task will update the POT file. Do this before making a pull request that includes changes to user-facing strings.
+
+3. Run `rake gettext:po[<lang>]` to create/update language-specific PO files. This step will be managed by the localization team, and will usually happen prior to a new release.
+
+4. When a PO file is updated, a git hook is used to automatically pull the new/updated strings into Transifex ready for translation.
+
+5. When the PO file reaches 100% translated and reviewed in Transifex, it is pulled back into the locale folder.
+
+6. PE checks the user's locale settings (the browser settings for web apps, or the system settings for the CLI). If we support the preferred locale, PE uses the PO file for that locale. Otherwise, it uses the default locale (en_US).
+
+## TODO
+
+1. Locale-specific formatting of numbers, dates, etc.
+2. Separate out the locales that are supported for testing/dev and production so we can add test translations without shipping them.

data/Rakefile

@@ -0,0 +1,5 @@
+require 'bundler/setup'
+
+require_relative './lib/gettext-setup/gettext_setup.rb'
+
+import 'lib/tasks/gettext.rake'

data/gettext-setup.gemspec

@@ -0,0 +1,21 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "gettext-setup"
+  spec.version       = "0.1"
+  spec.authors       = ["Puppet"]
+  spec.email         = ["info@puppet.com"]
+  spec.description   = "A gem to ease i18n"
+  spec.summary       = "A gem to ease internationalization with fast_gettext"
+  spec.homepage      = "https://github.com/puppetlabs/gettext-setup-gem"
+  spec.license       = "ASL2"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/gettext-setup.rb

@@ -0,0 +1 @@
+require 'gettext-setup/gettext_setup'

data/lib/gettext-setup/gettext_setup.rb

@@ -0,0 +1,82 @@
+# -*- encoding: utf-8 -*-
+require 'fast_gettext'
+require 'yaml'
+
+module GettextSetup
+  @@config = nil
+
+  # `locales_path` should include:
+  # - config.yaml
+  # - a .pot file for the project
+  # - i18n directories for languages, each with a .po file
+  def self.initialize(locales_path)
+    config_path = File.absolute_path('config.yaml', locales_path)
+    @@config = YAML.load_file(config_path)['gettext']
+    @@locales_path = locales_path
+
+    # Make the translation methods available everywhere
+    Object.send(:include, FastGettext::Translation)
+
+    # Define our text domain, and set the path into our root.  I would prefer to
+    # have something smarter, but we really want this up earlier even than our
+    # config loading happens so that errors there can be translated.
+    #
+    # We use the PO files directly, since it works about as efficiently with
+    # fast_gettext, and avoids all the extra overhead of compilation down to
+    # machine format, etc.
+    FastGettext.add_text_domain(config['project_name'],
+                                :path => locales_path,
+                                :type => :po,
+                                :ignore_fuzzy => false)
+    FastGettext.default_text_domain = config['project_name']
+
+    # Likewise, be explicit in our default language choice.
+    FastGettext.default_locale = default_locale
+    FastGettext.default_available_locales = locales
+  end
+
+  def self.locales_path
+    @@locales_path
+  end
+
+  def self.config
+    @@config
+  end
+
+  def self.default_locale
+    config['default_locale'] || "en"
+  end
+
+  def self.locales
+    explicit = Dir.glob(File::absolute_path('*/*.po', locales_path)).map do |x|
+      File::basename(File::dirname(x))
+    end
+    (explicit + [ default_locale]).uniq
+  end
+
+  # Given an HTTP Accept-Language header return the locale with the highest
+  # priority from it for which we have a locale available. If none exists,
+  # return the default locale
+  def self.negotiate_locale(accept_header)
+    unless @@config
+      raise ArgumentError, "No config.yaml found! Use `GettextSetup.initialize(locales_path)` to locate your config.yaml"
+    end
+    return FastGettext.default_locale if accept_header.nil?
+    available_locales = accept_header.split(",").map do |locale|
+      pair = locale.strip.split(';q=')
+      pair << '1.0' unless pair.size == 2
+      pair[0] = FastGettext.default_locale if pair[0] == '*'
+      pair
+    end.sort_by do |(locale,qvalue)|
+      qvalue.to_f
+    end.select do |(locale,_)|
+      FastGettext.available_locales.include?(locale)
+    end
+    if available_locales and available_locales.last
+      available_locales.last.first
+    else
+      # We can't satisfy the request preference. Just use the default locale.
+      default_locale
+    end
+  end
+end

data/lib/tasks/gettext.rake

@@ -0,0 +1,66 @@
+# require 'bundler'
+# puts File.absolute_path('Gemfile', Dir.pwd)
+# Bundler.read_file(File.absolute_path('Gemfile', Dir.pwd))
+#
+require_relative '../gettext-setup/gettext_setup'
+#
+# GettextSetup.initialize(File.absolute_path('locales', Dir.pwd))
+
+namespace :gettext do
+
+  def locale_path
+    GettextSetup.locales_path
+  end
+
+  def text_domain
+    FastGettext.text_domain
+  end
+
+  def files_to_translate
+    GettextSetup.config['source_files'].map do |p|
+      Dir.glob(p)
+    end.flatten
+  end
+
+  def pot_file_path
+    File.join(locale_path, GettextSetup.config['project_name'] + ".pot")
+  end
+
+  desc "Update pot files"
+  task :pot do
+    package_name = GettextSetup.config['package_name']
+    project_name = GettextSetup.config['project_name']
+    bugs_address = GettextSetup.config['bugs_address']
+    copyright_holder = GettextSetup.config['copyright_holder']
+    version=`git describe`
+    system("rxgettext -o locales/#{project_name}.pot --no-wrap --sort-by-file " +
+           "--add-comments --msgid-bugs-address '#{bugs_address}' " +
+           "--package-name '#{package_name}' " +
+           "--package-version '#{version}' " +
+           "--copyright-holder='#{copyright_holder}' --copyright-year=#{Time.now.year} " +
+           "#{files_to_translate.join(" ")}")
+    puts "POT file locales/#{project_name}.pot has been updated"
+  end
+
+  desc "Update po file for a specific language"
+  task :po, [:language] do |_, args|
+    language = args.language || ENV["LANGUAGE"]
+
+    # Let's do some pre-verification of the environment.
+    if language.nil?
+      puts "You need to specify the language to add. Either 'LANGUAGE=eo rake gettext:po' or 'rake gettext:po[LANGUAGE]'"
+      next
+    end
+
+    language_path = File.join(locale_path, language)
+    mkdir_p(language_path)
+
+    po_file_path = File.join(language_path,
+                             GettextSetup.config['project_name'] + ".po")
+    if File.exists?(po_file_path)
+      system("msgmerge -U #{po_file_path} #{pot_file_path}")
+    else
+      system("msginit --no-translator -l #{language} -o #{po_file_path} -i #{pot_file_path}")
+    end
+  end
+end

data/locales/config-sample.yaml

@@ -0,0 +1,22 @@
+---
+# 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: 'sinatra-i18n'
+  # 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: Sinatra i18n demo
+  # The locale that the default messages in the .pot file are in
+  default_locale: en
+  # The email used for sending bug reports.
+  bugs_address: docs@puppetlabs.com
+  # The holder of the copyright.
+  copyright_holder: Puppet Labs, LLC.
+  # Patterns for +Dir.glob+ used to find all files that might contain
+  # translatable content, relative to the project root directory
+  source_files:
+    - 'app.rb'
+    - 'lib/**/*.rb'

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: gettext-setup
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Puppet
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2016-06-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  name: bundler
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: rake
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A gem to ease i18n
+email:
+- info@puppet.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- gettext-setup.gemspec
+- lib/gettext-setup.rb
+- lib/gettext-setup/gettext_setup.rb
+- lib/tasks/gettext.rake
+- locales/config-sample.yaml
+homepage: https://github.com/puppetlabs/gettext-setup-gem
+licenses:
+- ASL2
+metadata: {}
+post_install_message:
+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.4
+signing_key:
+specification_version: 4
+summary: A gem to ease internationalization with fast_gettext
+test_files: []
+has_rdoc: