Merge branch 'i18n' of https://github.com/rails-taiwan/railsbridge-docs into rails-taiwan-i18n

Author: tjgrathwell

Gemfile

@@ -13,6 +13,7 @@ gem 'coderay'
 gem "deckrb", "~> 0.5.2"
 gem "sass"
 gem "redcarpet"
+gem "i18n", "~> 0.6.9"
 
 group :development do
   gem "wrong", "~> 0.7.0"

Gemfile.lock

@@ -101,6 +101,7 @@ DEPENDENCIES
   erector (~> 0.10.0)
   eventmachine (~> 1.0.3)
   files (~> 0.3.0)
+  i18n (~> 0.6.9)
   nokogiri
   rack-codehighlighter
   rack-test

README.md

@@ -33,9 +33,32 @@ Then open <http://localhost:9292> in a web browser, and verify that you can navi
 To serve sites from "sites/en", use `rake run` or a vanilla deploy.
 
 To server sites from another locale (say, "es" or Spanish)...
-  * Locally, use the SITE_LOCALE environment variable: `SITE_LOCALE=es rake run`
-  * On a server, make the server respond to a locale subdomain: `http://es.railsbridge.org`
-  * Or to temporarily test, use a `locale` or `l` parameter: `http://docs.railsbridge.org/?l=es` (note that in this mode, links are not rewritten, so if they fail you will have to manually add the parameter again)
+
+### Run Localized Site Locally
+
+    $ SITE_LOCALE=es rake run
+
+The server listens on `0.0.0.0:9292`.
+
+Now you have to setup subdomain for the site. If you have Pow, run:
+
+    $ echo 9292 > ~/.pow/railsbridge # works for any subdomain
+
+If you don't have Pow, add the following line to `/etc/hosts`:
+
+    127.0.0.1 es.railsbridge.dev # works for single subdomain
+
+Now you can access `http://es.railsbridge.dev:9292` for debugging.
+
+### Running on a Server
+
+Just make sure the server responds to a locale subdomain: `http://es.railsbridge.org`
+
+### Temporary Testing
+
+Use a `locale` or `l` parameter: `http://docs.railsbridge.org/?l=es`.
+
+Note that in this mode, links are not rewritten, so if they fail you will have to manually add the parameter again.
 
 ## Contributing
 

app.rb

@@ -1,6 +1,8 @@
 require 'sinatra'
 require 'digest/md5'
 require 'erector'
+require 'i18n'
+require 'i18n/backend/fallbacks'
 
 #require 'wrong'
 #include Wrong::D
@@ -22,15 +24,28 @@
 class InstallFest < Sinatra::Application   # todo: use Sinatra::Base instead, with more explicit config
   include Erector::Mixin
 
+  # Set available locales in Array of Strings; this is also used when
+  # checking availability in dynamic locale assigment, so must be as Strings.
+  AVAILABLE_LOCALES = %w(en es)
+
+  configure do
+    I18n::Backend::Simple.send(:include, I18n::Backend::Fallbacks)
+    I18n.load_path = Dir[File.join(settings.root, 'locales', '*.yml')]
+    I18n.backend.load_translations
+
+    I18n.available_locales = AVAILABLE_LOCALES
+    I18n.enforce_available_locales = true
+    I18n.default_locale = :en
+  end
+
   def initialize
     super
     @here = File.expand_path(File.dirname(__FILE__))
     @default_sites = {en: "docs", es: "hola"}
-    @default_locale = "en"
   end
 
-  attr_reader :here, :default_locale
-  attr_writer :default_site, :default_locale
+  attr_reader :here
+  attr_writer :default_site
 
   # todo: test
   # returns the most-specific hostname component, e.g. "foo" for "foo.example.com"
@@ -42,7 +57,7 @@ def default_site
     if host && sites.include?(site = subdomain)
       site
     else
-      @default_sites[locale.to_sym]
+      @default_sites[I18n.locale.to_sym] # no symbol DoS because it's whitelisted
     end
   end
 
@@ -55,7 +70,7 @@ def site_dir
   end
 
   def sites_dir
-    Site.sites_dir(locale)
+    Site.sites_dir(I18n.locale)
   end
 
   def sites
@@ -68,11 +83,18 @@ def redirect_sites
     }
   end
 
-  def locale
+  before do
+    begin
+      I18n.locale = dynamic_locale
+    rescue I18n::InvalidLocale
+      I18n.locale = I18n.default_locale
+    end
+  end
+
+  def dynamic_locale
     (params && (params[:locale] or params[:l])) or
-      (host && subdomain =~ /^..$/ && subdomain) or   # note: only allows 2-char locales for now -- should check against a list of locales
-      (ENV['SITE_LOCALE']) or
-      default_locale
+      (host && AVAILABLE_LOCALES.include?(subdomain) && subdomain) or
+      (ENV['SITE_LOCALE'])
   end
 
   def src
@@ -103,7 +125,7 @@ def render_page
         doc_path: doc_path,
         back: params[:back],
         src: src,
-        locale: locale,
+        locale: I18n.locale,
       }
 
       case ext

lib/contents.rb

@@ -228,7 +228,7 @@ def content
       toc_list(mark_open_and_closed(hierarchy)[:items])
 
       unless orphans.empty?
-        h1 "Other Pages"
+        h1 I18n.t("general.other_pages")
         ul do
           orphans.each { |orphan| toc_link orphan }
         end
@@ -237,7 +237,7 @@ def content
       if has_collapsables(hierarchy)
         span class: "expand-all" do
           i class: "fa fa-arrows-alt"
-          text "Expand All"
+          text I18n.t("general.expand_all")
         end
       end
     end

lib/doc_page.rb

@@ -121,10 +121,15 @@ def body_content
         doc_content
       }
       if @back
+        # Encode page name and fragment name separately so that
+        # the fragment indicator '#' won't be escaped.
+        page_name, fragment = @back.split('#')
+        back_url = [URI.escape(page_name), URI.escape(fragment)].join('#')
+
         div.back {
-          text "Back to "
-          a(class: "back", href: URI.escape(@back, URI::PATTERN::RESERVED)) do
-            text Titleizer.title_for_page(@back.split('#').first)
+          text I18n.t("general.back_to") + " "
+          a(class: "back", href: back_url) do
+            text Titleizer.title_for_page(page_name)
           end
         }
       end

lib/site.rb

@@ -5,7 +5,7 @@ class Site
   @@project_root = File.dirname(@@here)
 
   def self.sites_dir locale = "en"
-    sites_dir = File.join(["sites", locale].compact)
+    sites_dir = File.join(["sites", locale.to_s].compact)
     File.expand_path(sites_dir, @@project_root)
   end
 

lib/step.rb

@@ -63,21 +63,13 @@ def insert file
 
   ## steps
 
-  @@header_sections = {
-    steps:"Steps",
-    explanation:"Explanation",
-    overview:"Overview",
-    discussion:"Discussion Items",
-    hints:"Hints",
-    challenge:"Challenge(s)",
-    tools_and_references:"Tools and References",
-    requirements:"Requirements to advance",
-  }
-
-  @@header_sections.each do |type, header|
-    define_method type do |&block|
+  %w[
+    steps explanation overview discussion hints challenge 
+    tools_and_references requirements
+  ].each do |type|
+    define_method type.to_sym do |&block|
       div :class => type do
-        h1 header
+        h1 I18n.t(type, :scope => "header_section")
         blockquote do
           block.call if block
         end
@@ -92,7 +84,8 @@ def step name = nil, options = {}
     div :class => "step", :title => name do
       h1 do
         widget BigCheckbox
-        prefix "Step #{num}" + (!name.nil? ? ': ' : '')
+        prefix I18n.t("general.step_title", :num => num) +
+              (!name.nil? ? I18n.t("general.step_title_suffix") : '')
         text name
       end
       _render_inner_content &Proc.new if block_given?
@@ -101,7 +94,7 @@ def step name = nil, options = {}
 
 
   def link name, options = {}
-    options = {caption: LINK_CAPTION}.merge(options)
+    options = {caption: I18n.t("captions.link")}.merge(options)
     p :class => "link" do
       text options[:caption]
       text " "
@@ -114,7 +107,7 @@ def link_without_toc name
   end
 
   def _escaped str
-    URI.escape(str, URI::PATTERN::RESERVED)
+    URI.escape(str)
   end
 
   def simple_link name, options={}
@@ -135,8 +128,9 @@ def simple_link name, options={}
   def next_step name
     div :class => "step next_step" do
       h1 do
-        prefix "Next Step:"
+        prefix I18n.t("general.next_step")
       end
+      # FIXME: Translate with i18n. Currently it is hard to get site_name.
       link name
     end
   end
@@ -150,7 +144,7 @@ def option name
     num = next_step_number
     a(:name => "step#{current_anchor_num}")
     h1 :class => "option" do
-      span "Option #{num}: "
+      span I18n.t("general.option", :num => num)
       text name
     end
     _render_inner_content &Proc.new if block_given?
@@ -175,7 +169,7 @@ def section text
 
   def verify text = nil
     div :class=> "verify" do
-      h1 "Verify #{text}"
+      h1 I18n.t("general.verify", :text => text)
       blockquote do
         yield
       end
@@ -184,7 +178,7 @@ def verify text = nil
 
   def goals
     div :class => "goals" do
-      h1 "Goals"
+      h1 I18n.t("general.goals")
       ul do
         yield
       end
@@ -255,15 +249,8 @@ def error_box(error)
 
   ## special
 
-  # todo: i18n
-  TERMINAL_CAPTION = "Type this in the terminal:"
-  IRB_CAPTION = "Type this in irb:"
-  RESULT_CAPTION = "Expected result:"
-  FUZZY_RESULT_CAPTION = "Approximate expected result:"
-  LINK_CAPTION = "Go on to"
-
   def console(commands)
-    console_with_message(TERMINAL_CAPTION, commands)
+    console_with_message(I18n.t('captions.terminal'), commands)
   end
 
   def console_with_message(message, commands)
@@ -284,21 +271,21 @@ def source_code_with_message(text, *args)
 
   def irb msg
     div :class => "console" do
-      span IRB_CAPTION
+      span I18n.t("captions.irb")
       pre msg
     end
   end
 
   def type_in_file filename, msg
     div do
-      span "Type this in the file #{filename}:"
+      span I18n.t("general.type_in_file", :filename => filename)
       source_code :ruby, msg
     end
   end
 
   def further_reading
     div :class => "further-reading" do
-      h1 "Further Reading"
+      h1 I18n.t("general.further_reading")
       blockquote do
         yield
       end
@@ -307,15 +294,15 @@ def further_reading
 
   def result text
     div :class => "result" do
-      span RESULT_CAPTION
+      span I18n.t("captions.result")
       pre text.strip_heredoc
     end
   end
 
   def fuzzy_result fuzzed_text
     fuzzed_text = fuzzed_text.strip_heredoc
     div :class => "result fuzzy-result" do
-      span FUZZY_RESULT_CAPTION
+      span I18n.t("captions.fuzzy_result")
       remaining_text = fuzzed_text
       pre do
         while match = remaining_text.match(/(.*?){FUZZY}(.*?){\/FUZZY}(.*)/m)
@@ -325,7 +312,7 @@ def fuzzy_result fuzzed_text
         end
         text remaining_text
       end
-      div "The greyed-out text may differ and is not important.", :class => 'fuzzy-hint'
+      div I18n.t("general.fuzzy_hint"), :class => 'fuzzy-hint'
     end
   end
 

locales/en.yml

@@ -0,0 +1,31 @@
+en:
+  captions:
+    terminal: "Type this in the terminal:"
+    irb: "Type this in irb:"
+    result: "Expected result:"
+    fuzzy_result: "Approximate expected result:"
+    link: "Go on to"
+
+  general:
+    type_in_file: "Type this in the file %{filename}:"
+    further_reading: "Further Reading"
+    fuzzy_hint: "The greyed-out text may differ and is not important."
+    step_title: "Step %{num}"
+    step_title_suffix: ": "
+    next_step: "Next Step:"
+    option: "Option %{num}: "
+    verify: "Verify %{text}"
+    goals: "Goals"
+    expand_all: "Expand All"
+    other_pages: "Other Pages"
+    back_to: "Back to"
+
+  header_section:
+    steps: "Steps"
+    explanation: "Explanation"
+    overview: "Overview"
+    discussion: "Discussion Items"
+    hints: "Hints"
+    challenge: "Challenge(s)"
+    tools_and_references: "Tools and References"
+    requirements: "Requirements to advance"