use subdomain, param, or environment variable to specify locale

Author: alexch

README.md

@@ -12,7 +12,7 @@ PHPBridge by standing on their shoulders and building up.
 
 This is a Sinatra app, deployed at <http://docs.railsbridge.org>. The PHPBridge documentation project is home to a few subprojects, including the PHPBridge installfest instructions, which leads students through the various complicated setup instructions for getting PHP, MySQL, Git, etc. installed on their computer (whatever combination of computer, OS, and version they happened to bring to the workshop!), as well as the PHPBridge workshop "Suggestotron" curriculum.
 
-Each subproject (a "site") comprises files stored under the "sites" directory; for instance, the installfest instructions are located at ROOT/sites/installfest, while the intro PHP curriculum can be found under ROOT/sites/intro-to-php.
+Each subproject (a "site") comprises files stored under the "sites" directory; for instance, the installfest instructions are located at ROOT/sites/en/installfest, while the intro PHP curriculum can be found under ROOT/sites/en/intro-to-php.
 
 These files can be in any of these formats:
 
@@ -31,9 +31,18 @@ These files can be in any of these formats:
 If the above fails (say, because `rerun` doesn't work on your system), try
 
     rackup
-    
+
 Then open <http://localhost:9292> in a web browser, and verify that you can navigate the installfest slides.
 
+## Locales
+
+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)
+
 ## Contributing
 
 Check out [CONTRIBUTING.md](CONTRIBUTING.md) to see how to join our [list of contributors](https://github.com/railsbridge/docs/contributors)!

app.rb

@@ -2,8 +2,8 @@
 require 'digest/md5'
 require 'erector'
 
-# require 'wrong'
-# include Wrong::D
+#require 'wrong'
+#include Wrong::D
 
 here = File.expand_path File.dirname(__FILE__)
 lib = File.expand_path "#{here}/lib"
@@ -25,11 +25,11 @@ class InstallFest < Sinatra::Application   # todo: use Sinatra::Base instead, wi
   def initialize
     super
     @here = File.expand_path(File.dirname(__FILE__))
-    @default_site = "docs"
+    @default_sites = {en: "docs", es: "hola"}
     @default_locale = "en"   # nil for English   # todo: make a cleaner way to switch default locales
   end
 
-  attr_reader :here
+  attr_reader :here, :default_locale
   attr_writer :default_site, :default_locale
 
   # todo: test
@@ -42,7 +42,7 @@ def default_site
     if host && sites.include?(site = subdomain)
       site
     else
-      @default_site
+      @default_sites[locale.to_sym]
     end
   end
 
@@ -67,11 +67,12 @@ def redirect_sites
       'curriculum' => 'intro-to-php'
     }
   end
-  
+
   def locale
-    (params && params[:locale]) or
+    (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
-      @default_locale
+      (ENV['SITE_LOCALE']) or
+      default_locale
   end
 
   def src
@@ -102,6 +103,7 @@ def render_page
         doc_path: doc_path,
         back: params[:back],
         src: src,
+        locale: locale,
       }
 
       case ext
@@ -135,13 +137,6 @@ def render_page
 
   before do
     expires 3600, :public
-
-    if request.path =~ /^\/es(.*)/
-      params[:locale] = "es"
-      request.env["PATH_INFO"] = $1
-      # p request.env["PATH_INFO"]
-      # p request.params[:locale]
-    end
   end
 
   get '/favicon.ico' do
@@ -151,15 +146,16 @@ def render_page
   get "/" do
     redirect "/#{default_site}/"
   end
-  
+
   get "/:site/:name/src" do
     begin
       RawPage.new(
         site_name: params[:site],
         page_name: params[:name],
         doc_title: doc_path.split('/').last,
         doc_path: doc_path,
-        src: src
+        src: src,
+        locale: locale,
       ).to_html
     rescue Errno::ENOENT => e
       p e
@@ -184,7 +180,7 @@ def render_page
     # remove any extraneous slash from otherwise well-formed page URLs
     redirect request.fullpath.chomp('/')
   end
-  
+
   get "/:site/:name" do
     site_name = params[:site]
     if redirect_sites[site_name]

lib/doc_page.rb

@@ -6,7 +6,7 @@
 require 'html5_page'
 
 class DocPage < Html5Page
-  needs :site_name, :doc_title, :doc_path, :page_name, :src
+  needs :site_name, :doc_title, :doc_path, :page_name, :src, :locale
   needs :back => nil
   attr_reader :site_name, :doc_title, :page_name, :src
 
@@ -62,7 +62,7 @@ def file_name
   end
 
   def git_url
-    "https://github.com/phpbridge/docs/blob/master/sites/#{@site_name}/#{file_name}"
+    "https://github.com/phpbridge/docs/blob/master/sites/#{@locale}/#{@site_name}/#{file_name}"
   end
 
   def src_url
@@ -98,7 +98,7 @@ def body_content
 
         li(class: "dropdown") {
           a("curriculum", href: "#", class: "dropdown-toggle", "data-toggle" => "dropdown")
-          widget SiteIndex, site_name: site_title
+          widget SiteIndex, site_name: site_name, locale: @locale
         }
 
         top_links.each do |top_link|

lib/site_index.rb

@@ -1,14 +1,10 @@
 class SiteIndex < Erector::Widget
-  needs :site_name
+  needs :site_name, :locale
   attr_accessor :site_name
 
-  def initialize(options)
-    self.site_name = options[:site_name]
-  end
-
   def sites
     return @sites if @sites
-    @sites = Dir.glob("#{Site.sites_dir}/**").map { |filename| File.basename(filename) }.sort
+    @sites = Dir.glob("#{Site.sites_dir(@locale)}/**").map { |filename| File.basename(filename) }.sort
   end
 
   def site_link site

spec/app_spec.rb

@@ -11,20 +11,21 @@ class ::InstallFest
   def dup *args
     @@latest_instance = super
   end
+
   def self.latest_instance
     @@latest_instance
   end
 end
 
 describe InstallFest do
-  include Rack::Test::Methods
+  include Rack::Test::Methods # see http://www.sinatrarb.com/testing.html
 
   def app
     InstallFest
   end
 
   # find the actual InstallFest app, discarding Rack middleware
-  def true_app    
+  def true_app
     InstallFest.latest_instance
   end
 
@@ -41,7 +42,7 @@ def get! *args
   end
 
   it "redirects / to the default site" do
-    get! "/"    
+    get! "/"
     assert { last_request.path == "/docs/" }
   end
 
@@ -63,22 +64,31 @@ def get! *args
     # note: I'd rather pass settings into the constructor, but Sinatra uses that interface (for a downstream app)
 
     before { get '/' }
-    
-    it "accepts default_site via setter" do
-      true_app.default_site = "intro-to-rails"
-      assert { true_app.default_site == "intro-to-rails" }
-    end
-    
+
     describe "learns the locale from" do
       it "the locale parameter" do
         true_app.params = {locale: 'es'}
         assert { true_app.locale == 'es' }
       end
 
+      it "the l parameter" do
+        true_app.params = {l: 'es'}
+        assert { true_app.locale == 'es' }
+      end
+
       it "the subdomain" do
         true_app.request = Rack::Request.new({"HTTP_HOST" => "es.example.com"})
         assert { true_app.locale == 'es' }
       end
+
+      it "the SITE_LOCALE environment var" do
+        begin
+          ENV["SITE_LOCALE"] = "es"
+          assert { true_app.locale == 'es' }
+        ensure
+          ENV["SITE_LOCALE"] = nil
+        end
+      end
     end
   end
 
@@ -88,14 +98,15 @@ def get! *args
     follow_redirect! while last_response.redirect?
     assert { last_request.path == "/docs/" }
   end
-  
+
   describe "in the 'es' locale" do
-    it "uses the 'es' subdir as the sites_dir" do   
+    it "uses the 'es' subdir as the sites_dir" do
       get "/", locale: "es"
-      
+
       es_dir = File.expand_path(File.join(__FILE__, "..", "..", "sites", "es"))
       assert { true_app.sites_dir == es_dir }
     end
+
   end
 
   describe "page headers" do

spec/markdown_spec.rb

@@ -21,7 +21,8 @@
       site_name: "greetings",
       page_name: 'hello',
       doc_title: "Hello",
-      doc_path: "/tmp/hello.step"
+      doc_path: "/tmp/hello.step",
+      locale: "en"
     )
     html_doc = Nokogiri.parse(page.to_html)
     main_html = html_doc.css("main").first.serialize(:save_with => 0).chomp

spec/site_index_spec.rb

@@ -5,7 +5,7 @@
 
 describe SiteIndex do
   before :all do
-    @site_index = SiteIndex.new(site_name: 'frontend')
+    @site_index = SiteIndex.new(site_name: 'frontend', locale: 'en')
   end
 
   it "lists all sites in the /sites/ directory" do

spec/step_page_spec.rb

@@ -7,13 +7,14 @@
   # functional test -- brittle
   it "renders a step file" do
     BigCheckbox.number = 1
-    
+
     src = "step 'hello'"
     page = StepPage.new(src: src,
       site_name: "greetings",
       page_name: 'hello',
       doc_title: "Hello",
-      doc_path: "/tmp/hello.step"
+      doc_path: "/tmp/hello.step",
+      locale: "en"
     )
     html_doc = Nokogiri.parse(page.to_html)
     main_html = html_doc.css("main").first.serialize(:save_with => 0).chomp