jekyll-locale 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 73cdeebfabff92747661cda740330d4fadb99139
-  data.tar.gz: 6bb5b58bdb7420b41ea12c5b2d3f5f6267e93623
+  metadata.gz: 95f578476bc1531c27696fd1218bc914ec176686
+  data.tar.gz: e3723615a5e94829370795bcc51a4d70c27b20db
 SHA512:
-  metadata.gz: c1182409d6e2c03b9aec4a8af42fbe9ccffbc72b956df482931e47ee3d6ba534b5e9055025cb8201a3709f00cd849aa2886b22122789aff6f2b2af97a8d1fc35
-  data.tar.gz: ba66142dc23a732e769a10085cdcf0135a4d33d485fe61d5f90788a5ab541cb2dab8491443865ab9e66a9179e1b19a3e0a55ebe65d335eb24a008a7073fdbff9
+  metadata.gz: 8cd1ed64b59d8f5f8f308abba21bc6d1cbf29ed54f79d317dcd6741d1b73c37ebed95a12e2349c0bf65e5d3531394fcefb83c6a0edde6c40dac85e606a93080b
+  data.tar.gz: d37d608b72baff43775909273f1ebe3cf73452d1dcac35baa7bf168174d379fccc8fa4cd4d5266260a654cbb14e9292acad2f854a440c1b320c43f661b96ed79

data/README.md

@@ -1,3 +1,129 @@
 # Jekyll Locale
 
-A localization plugin for Jekyll
+A localization plugin for Jekyll.
+
+
+## Features
+
+* Exposes a `{{ locale }}` object for your Liquid templates. The *payload* for this object is derived from data files and
+  has been *preconfigured* with the following:
+
+    ```yaml
+    locale      : en       # Sets the 'default locale' for the site
+    locales_dir : locales  # Sets the base location for translation data, within your configured `data_dir`.
+                           # Therefore, this setting implies that the plugin looks for translation data in
+                           # either `_data/locales/` or a data file named `locales`. e.g. `_data/locales.yml`.
+    ```
+  Ergo, `{{ locale }}` is simply a *syntactic sugar* for the construct `{{ site.data[site.locales_dir][site.locale] }}`.
+* Generates a *copy* of every page that renders into a HTML file, and every document set to be written, and renders
+  them into dedicated urls prepended by a supported locale.
+  For example, if one were to configure the plugin with `available_locales: ["de", "fr", "en", "es"]`, then a file
+  named `about.md` with custom permalink set to `/about/` will result in the following files:
+    * `_site/about/index.html`
+    * `_site/de/about/index.html`
+    * `_site/es/about/index.html`
+    * `_site/fr/about/index.html`
+
+
+## Usage
+
+1. Add plugin to the `:jekyll_plugins` group in your Gemfile:
+
+    ```ruby
+    group :jekyll_plugins do
+      gem "jekyll-locale", "~> 0.1"
+    end
+    ```
+
+2. Decide what the default locale for your site is going to be, what other locales need to be rendered, and where you'd
+  place the translation data files. Then edit your config file to override the default plugin configuration, as required.
+  (See above section for default settings). For example, to render the site with data for just the custom `fr` locale:
+
+    ```yaml
+    # _config.yml
+
+    author: John Doe
+    locale: "fr"
+    ```
+
+    But if you'd like the site to be rendered using both the default `en` and custom `fr` locales, then
+
+    ```yaml
+    # _config.yml
+
+    author: John Doe
+    available_locales: ["fr"] # or ["fr", "en"] if you want
+    ```
+
+3. Prepare your locale data file(s) with appropriate key-value pairs. For example,
+
+    ```yaml
+    # _data/locales.yml
+
+    en:
+      home-page: Home
+      about me : About Me
+      portfolio: Portfolio
+    fr:
+      home-page: Accueil
+      about me : À propos
+      portfolio: Portefeuille
+    ```
+    *(Note the use of heterogeneous format of keys..)*
+
+4. Use the data above in a template or a document through the {{ locale }} object. For example,
+
+    ```
+    List of link names in my navbar:
+    * {{ locale.home_page }}
+    * {{ locale.about_me }}
+    * {{ locale.portfolio }}
+    ```
+    *(Note that the ids passed to the `locale` object contain an underscore instead.)*
+    The locale data keys are stored internally as `snake_case` strings. So `about me` or `about-me` will always be stored
+    as `about_me` internally and the corresponding value can only be retrieved by using the snake_cased key.
+
+    Additionally, every page can determine its own locale via the `{{ page.locale }} construct. For example,
+
+    ```html
+    <!DOCTYPE html>
+    <html lang="{{ page.locale }}">
+    ```
+
+
+## Advanced Usage
+
+Each generated locale page is aware of its canonical page and its sibling locale page (for sites rendering three or more
+locales) and can be used to render meta tags for optimal SEO.
+
+Adding the following Liquid construct inside your `<head />` tag will render the markup that tells the crawler how the
+pages are related to each other:
+
+```html
+{% for item in page.hreflangs %}
+  <link rel="{{ item.relation }}" hreflang="{{ item.locale }}" href="{{ item.url | absolute_url }}" />
+{% endfor %}
+```
+
+For example, `about.md` page with `permalink: /about/` in a site setup to render for locales `["en", "es", "fr"]`
+and hosted at `http://example.com` will render with the following:
+
+```html
+  <link rel="canonical" hreflang="en" href="http://example.com/about/" />
+  <link rel="alternate" hreflang="es" href="http://example.com/es/about/" />
+  <link rel="alternate" hreflang="fr" href="http://example.com/fr/about/" />
+```
+
+*The above use of `rel="canonical"` with `hreflang` attribute is generally frowned upon and not recommended by Google.* </br>
+Instead filter out the canonical url from the for-loop, and render the canonical link as an `alternate` with the
+`x-default` tag, along with a self-referencing declaration:
+
+```html
+  <link rel="alternate" hreflang="{{ page.locale }}" href="{{ page.url | absolute_url }}" />
+{% for item in page.hreflangs %}
+{% unless item.relation == 'canonical' %}
+  <link rel="{{ item.relation }}" hreflang="{{ item.locale }}" href="{{ item.url | absolute_url }}" />
+{% endunless %}
+{% endfor %}
+  <link rel="alternate" hreflang="x-default" href="{{ page.url | absolute_url }}" />
+```

data/lib/jekyll/locale/drop.rb

@@ -7,4 +7,10 @@ module Jekyll
     mutable false
     private def_delegator :@obj, :data, :fallback_data
   end
+
+  #
+
+  class Locale::PageDrop < Locale::Drop
+    def_delegators :@obj, :locale, :url
+  end
 end

data/lib/jekyll/locale/handler.rb

@@ -2,29 +2,60 @@
 
 module Jekyll
   class Locale::Handler
+    attr_writer :current_locale
+
     def initialize(site)
       @site   = site
       @config = site.config
     end
 
     def reset
-      @data = nil
+      @locale_data = nil
+      @portfolio   = nil
     end
 
     def data
-      @data ||= begin
-        fallback = site.site_data.dig(locales_dir, locale)
-        return {} unless fallback.is_a?(Hash)
+      locale_data[current_locale] || locale_data[default_locale]
+    end
 
-        # transform hash to one with "latinized lowercased string keys"
-        Jekyll::Utils.snake_case_keys(fallback)
+    def portfolio
+      @portfolio ||= (site.docs_to_write + html_pages)
+    end
+
+    def available_locales
+      @available_locales ||= begin
+        locales = Array(config["available_locales"]) - [default_locale]
+        locales.compact!
+        locales
       end
     end
 
+    def current_locale
+      @current_locale ||= default_locale
+    end
+
+    def default_locale
+      @default_locale ||= begin
+        value = config["locale"]
+        value.to_s.empty? ? "en" : value
+      end
+    end
+
+    def inspect
+      "#<#{self.class} @site=#{site}>"
+    end
+
     private
 
     attr_reader :site, :config
 
+    def html_pages
+      @html_pages ||= begin
+        pages = site.site_payload["site"]["html_pages"] || []
+        pages.reject { |page| page.name == "404.html" }
+      end
+    end
+
     def locales_dir
       @locales_dir ||= begin
         value = config["locales_dir"]
@@ -32,10 +63,13 @@ module Jekyll
       end
     end
 
-    def locale
-      @locale ||= begin
-        value = config["locale"]
-        value.to_s.empty? ? "en" : value
+    def locale_data
+      @locale_data ||= begin
+        ldata = site.site_data[locales_dir]
+        return {} unless ldata.is_a?(Hash)
+
+        # transform hash to one with "latinized lowercased string keys"
+        Jekyll::Utils.snake_case_keys(ldata)
       end
     end
   end

data/lib/jekyll/locale/page.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Locale::Page < Page
+    extend Forwardable
+
+    attr_reader    :canon, :locale
+    attr_accessor  :data, :content, :output
+
+    def_delegators :@canon, :site, :extname, :relative_path
+
+    def initialize(canon, locale)
+      @canon  = canon
+      @locale = locale
+    end
+
+    def url
+      @url ||= File.join(locale, canon.url)
+    end
+
+    def to_liquid
+      @to_liquid ||= Locale::PageDrop.new(self)
+    end
+
+    def setup_hreflangs
+      @hreflangs = (canon.locale_pages + [canon] - [self]).map do |locale_page|
+        {
+          "locale"   => locale_page.locale || site.locale_handler.default_locale,
+          "relation" => locale_page.locale ? "alternate" : "canonical",
+          "url"      => locale_page.url,
+        }
+      end
+    end
+
+    def inspect
+      "#<#{self.class} @canon=#{canon.inspect} @locale=#{locale.inspect}>"
+    end
+    alias_method :to_s, :inspect
+  end
+end

data/lib/jekyll/locale/page_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Locale::PageGenerator < Generator
+    safe true
+    priority :lowest
+
+    def generate(site)
+      @site   = site
+      handler = site.locale_handler
+      return if handler.available_locales.empty?
+
+      handler.available_locales.each do |locale|
+        handler.portfolio.each do |canon_doc|
+          locale_page = Locale::Page.new(canon_doc, locale)
+          locale_page.content = canon_doc.content
+          locale_page.data    = canon_doc.data
+
+          # add locale_page to parent document and base array of pages
+          canon_doc.locale_pages << locale_page
+          site.pages << locale_page
+        end
+      end
+    end
+
+    def inspect
+      "#<#{self.class} @site=#{@site}>"
+    end
+  end
+end

data/lib/jekyll/locale/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Locale
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/jekyll/patches/site.rb

@@ -3,13 +3,13 @@
 module Jekyll
   class Drops::UnifiedPayloadDrop
     def locale
-      @locale ||= Jekyll::Locale::Drop.new(@obj.locale_handler)
+      @locale ||= Locale::Drop.new(@obj.locale_handler)
     end
   end
 
   class Site
     def locale_handler
-      @locale_handler ||= Jekyll::Locale::Handler.new(self)
+      @locale_handler ||= Locale::Handler.new(self)
     end
   end
 end

data/lib/jekyll/patches/utils.rb

@@ -47,7 +47,7 @@ module Jekyll
 
     private
 
-    # Replace each character sequence with a hyphen.
+    # Replace each character sequence with given character.
     #
     # See Utils#slugify for a description of the character sequence specified
     # by each mode.

data/lib/jekyll-locale.rb

@@ -3,13 +3,46 @@
 module Jekyll
   module Locale
     autoload :Drop,    "jekyll/locale/drop"
+    autoload :Page,    "jekyll/locale/page"
     autoload :Handler, "jekyll/locale/handler"
   end
+
+  #
+
+  module LocaleSupport
+    attr_reader :locale
+
+    def hreflangs
+      @hreflangs ||= locale_pages.map do |locale_page|
+        {
+          "locale"   => locale_page.locale,
+          "relation" => "alternate",
+          "url"      => locale_page.url,
+        }
+      end
+    end
+
+    def locale_pages
+      @locale_pages ||= []
+    end
+  end
+
+  # Enhance Jekyll::Page and Jekyll::Document classes
+  [Page, Document].each { |klass| klass.include LocaleSupport }
 end
 
+require_relative "jekyll/locale/page_generator"
+
 require_relative "jekyll/patches/site"
 require_relative "jekyll/patches/utils"
 
 Jekyll::Hooks.register :site, :after_reset do |site|
   site.locale_handler.reset
 end
+
+Jekyll::Hooks.register [:pages, :documents], :pre_render do |document, payload|
+  handler = document.site.locale_handler
+  handler.current_locale = document.locale
+  document.setup_hreflangs if document.is_a?(Jekyll::Locale::Page)
+  payload["page"]["hreflangs"] = document.hreflangs
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-locale
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ashwin Maroli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-21 00:00:00.000000000 Z
+date: 2018-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -36,6 +36,8 @@ files:
 - lib/jekyll-locale.rb
 - lib/jekyll/locale/drop.rb
 - lib/jekyll/locale/handler.rb
+- lib/jekyll/locale/page.rb
+- lib/jekyll/locale/page_generator.rb
 - lib/jekyll/locale/version.rb
 - lib/jekyll/patches/site.rb
 - lib/jekyll/patches/utils.rb