jekyll-locale 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 95f578476bc1531c27696fd1218bc914ec176686
-  data.tar.gz: e3723615a5e94829370795bcc51a4d70c27b20db
+  metadata.gz: d4e9bb6b38af90f2abe329414e61479a0afb06bb
+  data.tar.gz: 531866e46d63671cafc32c233f64ec263bfb3744
 SHA512:
-  metadata.gz: 8cd1ed64b59d8f5f8f308abba21bc6d1cbf29ed54f79d317dcd6741d1b73c37ebed95a12e2349c0bf65e5d3531394fcefb83c6a0edde6c40dac85e606a93080b
-  data.tar.gz: d37d608b72baff43775909273f1ebe3cf73452d1dcac35baa7bf168174d379fccc8fa4cd4d5266260a654cbb14e9292acad2f854a440c1b320c43f661b96ed79
+  metadata.gz: c817b57303dd42dca2f76aa8f7bc7e5349c63879afbb2382268ecc91da1fe199f0135fd0d468d2d35a769a29a7dd6c8bb2eb77eb8383a5fd4b1467fac670f789
+  data.tar.gz: bb6c4a7712ce0d12e130231179b49a813f4e7fdd37ceff9d298f6d5799330b9f35549c0cd2c856562148b19a2a32f0f50fe665c775cd06b90786f4e0cbeef60e

data/README.md

@@ -5,28 +5,94 @@ 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:
+* Exposes a `{{ locale }}` object for your Liquid templates that can be used to "translate" strings in your site easily.
+* Depending on configured `mode`, the plugin either 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, or, the plugin
+  "processes" only those files placed inside the plugin's configured **`content_dir`** .
 
-    ```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`
+
+## Configuration
+
+The plugin has been *preconfigured* with the following:
+
+```yaml
+localization:
+  mode       : manual     # Sets the 'handler mode'
+  locale     : en-US      # Sets the 'default locale' for the site
+  data_dir   : locales    # Sets the base location for *translation data*, within your *site's `data_dir`*.
+  content_dir: _locales   # Sets the base location for placing files to be re-rendered. Ignored in "auto mode".
+  locales_set: []         # A list of locales the site will re-render files into
+  exclude_set: []         # A list of file paths the site will not re-render in "auto" mode.
+```
+
+### `data_dir`
+
+This setting defines the base location for *the translation data*, within your site's configured `data_dir`. The value
+defaults to `"locales"`. This implies that the plugin looks for "translation data" in either `_data/locales/` or a data
+file named `locales`. e.g. `_data/locales.yml` or `_data/locales.json`, etc.
+
+Irrespective of the format, the data should be a Hash table / dictionary of key-value pairs where the main key should
+correspond to locale defined in the `locales_set` array or the default locale `en-US`, and the subkeys set to string
+values.
+
+### `content_dir`
+
+Ignored in "auto mode", this setting defines the base location for placing "the physical copies" of the canonical pages
+and documents. Refer `mode` sub-section below for further details.
+
+The default setting is `_locales`
+
+### `locales_set`
+
+Empty by default, this setting defines what locales to be used when "localizing" a site. Listing a locale (other than
+the default locale) will cause the entire site to render for that locale and the default locale while in "auto mode".
+
+### `locale`
+
+Set to `en-US` by default, this setting defines the default locale of the site and will not be prepended to the URL of
+the generated files.
+
+### `exclude_set`
+
+Empty by default, this setting defines what files to be *excluded* from being duplicated and re-rendered in the "auto"
+mode. Ignored in "manual" mode.
+
+### `mode`
+
+This setting defines the plugin's operation strategy.
+
+When set to **`auto`**, the plugin will initialize a generator that will simply duplicate *every page and document set
+to be written to destination*, and re-render them into destination, for every locale listed in the `locales_set:`
+array.
+
+This mode will increase your build times in proportion to the total number pages, writable-documents and locales listed
+but will result in simply the same canonical output and the canonical url prepended with an iterated locale.
+
+For example, if one were to configure the plugin with `locales_set: ["de", "fr", "en-US", "es"]`, then a file named
+`about.md` will result in the following files:
+  * `_site/about.html`
+  * `_site/de/about.html`
+  * `_site/es/about.html`
+  * `_site/fr/about.html`
+
+Setting `mode` to any other value will automatically default to `"manual"` which **requires** you to create physical
+files in a special directory (as configured under `localization["content_dir"]`) to render localized copies. The
+salient features of this mode are:
+  * The physical files are handled like any other file in the site, but, they **should partially mirror** their
+    counterpart — **their relative_paths should match**. Additionally, if an original file contains front matter,
+    the physical copy should contain front matter as well.
+  * The physical files should reside inside sub-folders that match the desired locale. For example, to "localize" a post
+    at path `movies/_posts/2018-09-24-hello.markdown` with locale `fr`, you should create the physical copy at path
+    `_locales/fr/movies/_posts/2018-09-24-hello.markdown`.
+  * Physical copies can render different content and into a different layout, if desired.
+  * Physical copies of posts and other writable *documents* can be rendered to a different `slug` by defining the `slug`
+    key in the front matter.
 
 
 ## Usage
 
+### Auto Mode
+
 1. Add plugin to the `:jekyll_plugins` group in your Gemfile:
 
     ```ruby
@@ -37,22 +103,27 @@ A localization plugin for Jekyll.
 
 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:
+  (See above section for default settings). For example, to render the entire site with data for just the custom `fr`
+  locale:
 
     ```yaml
     # _config.yml
 
     author: John Doe
-    locale: "fr"
+    localization:
+      mode: auto
+      locale: fr
     ```
 
-    But if you'd like the site to be rendered using both the default `en` and custom `fr` locales, then
+    But if you'd like the entire site to be rendered using both the default `en-US` and custom `fr` locales, then
 
     ```yaml
     # _config.yml
 
     author: John Doe
-    available_locales: ["fr"] # or ["fr", "en"] if you want
+    localization:
+      mode: auto
+      locales_set: ["fr"] # or ["fr", "en-US"] if you want
     ```
 
 3. Prepare your locale data file(s) with appropriate key-value pairs. For example,
@@ -90,6 +161,44 @@ A localization plugin for Jekyll.
     <html lang="{{ page.locale }}">
     ```
 
+### Manual Mode
+
+Similar to the *auto mode*, but requires the user to provide physical files in the configured `content_dir` with
+sub-directories that match the defined locales.
+
+For example, the following directory structure
+
+```
+.
+├── _config.yml
+├── _locales
+|  ├── es
+|  |  ├── tips/
+|  |  |  └── optimized-site.md
+|  |  ├── _posts/
+|  |  ├──└── 2018-09-30-hello-world.md
+|  ├── fr
+|  |  ├── _posts/
+|  └──└──└── 2018-09-30-hello-world.md
+├── _posts
+|  └── 2018-09-30-hello-world.md
+├── english
+|  └── its-a-new-day.md
+├── tips
+|  ├── optimized-site.md
+└──└── url-filters-in-templates.md
+```
+will result in the generation of just the following files:
+
+```
+_site/2018-09-30-hello-world.html
+_site/english/its-a-new-day.html
+_site/es/2018-09-30-hello-world.html
+_site/es/tips/optimized-site.html
+_site/fr/2018-09-30-hello-world.html
+_site/tips/optimized-site.html
+_site/tips/url-filters-in-templates.html
+```
 
 ## Advanced Usage
 
@@ -105,11 +214,11 @@ pages are related to each other:
 {% endfor %}
 ```
 
-For example, `about.md` page with `permalink: /about/` in a site setup to render for locales `["en", "es", "fr"]`
+For example, `about.md` page with `permalink: /about/` in a site setup to render for locales `["en-US", "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="canonical" hreflang="en-US" 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/" />
 ```

data/lib/jekyll/locale/auto_page.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Locale::AutoPage < Page
+    extend Forwardable
+    include Locale::Helper
+
+    attr_accessor  :data, :content, :output
+    def_delegators :@canon, :site, :extname, :relative_path
+
+    def initialize(canon, locale)
+      setup(canon, locale)
+      @path    = canon.path
+      @content = canon.content
+      @data    = canon.data
+    end
+
+    def url
+      @url ||= File.join("", locale, canon.url)
+    end
+
+    def to_liquid
+      @to_liquid ||= Locale::PageDrop.new(self)
+    end
+  end
+end

data/lib/jekyll/locale/document.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Locale::Document < Document
+    include Locale::Helper
+
+    def initialize(canon, locale)
+      setup(canon, locale)
+      @collection = canon.collection
+      @extname = File.extname(relative_path)
+      @has_yaml_header = nil
+      read
+
+      special_dir = draft? ? "_drafts" : @collection.relative_directory
+      categories_from_path(special_dir)
+
+      configure_data
+    end
+
+    def url_template
+      @url_template ||= File.join("", locale, super)
+    end
+  end
+end

data/lib/jekyll/locale/generator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class Locale::Generator < 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.filtered_portfolio.each do |canon_doc|
+          handler.append_document(Locale::AutoPage, canon_doc, locale, site.pages)
+        end
+      end
+    end
+
+    def inspect
+      "#<#{self.class} @site=#{@site}>"
+    end
+  end
+end

data/lib/jekyll/locale/handler.rb

@@ -4,9 +4,23 @@ module Jekyll
   class Locale::Handler
     attr_writer :current_locale
 
+    DEFAULT_CONFIG = {
+      "mode"        => "manual",
+      "locale"      => "en-US",
+      "data_dir"    => "locales",
+      "content_dir" => "_locales",
+      "locales_set" => [],
+      "exclude_set" => [],
+    }.freeze
+
     def initialize(site)
       @site   = site
-      @config = site.config
+      config  = site.config["localization"]
+      @config = if config.is_a?(Hash)
+                  Jekyll::Utils.deep_merge_hashes(DEFAULT_CONFIG, config)
+                else
+                  DEFAULT_CONFIG
+                end
     end
 
     def reset
@@ -15,16 +29,47 @@ module Jekyll
     end
 
     def data
-      locale_data[current_locale] || locale_data[default_locale]
+      locale_data[current_locale] || locale_data[default_locale] || {}
     end
 
     def portfolio
       @portfolio ||= (site.docs_to_write + html_pages)
     end
 
+    def filtered_portfolio
+      @filtered_portfolio ||= begin
+        portfolio.reject do |item|
+          item.relative_path =~ exclusion_regex
+        end
+      end
+    end
+
+    def read
+      available_locales.each do |locale|
+        portfolio.each do |canon_doc|
+          loc_page_path = site.in_source_dir(content_dirname, locale, canon_doc.relative_path)
+          next unless File.exist?(loc_page_path)
+          next unless Jekyll::Utils.has_yaml_header?(loc_page_path)
+
+          case canon_doc
+          when Jekyll::Page
+            append_document(Locale::Page, canon_doc, locale, site.pages)
+          when Jekyll::Document
+            append_document(Locale::Document, canon_doc, locale, site.docs_to_write)
+          end
+        end
+      end
+    end
+
+    def append_document(klass, canon_doc, locale, base_array)
+      locale_page = klass.new(canon_doc, locale)
+      canon_doc.locale_pages << locale_page
+      base_array << locale_page
+    end
+
     def available_locales
       @available_locales ||= begin
-        locales = Array(config["available_locales"]) - [default_locale]
+        locales = Array(config["locales_set"]) - [default_locale]
         locales.compact!
         locales
       end
@@ -35,9 +80,17 @@ module Jekyll
     end
 
     def default_locale
-      @default_locale ||= begin
-        value = config["locale"]
-        value.to_s.empty? ? "en" : value
+      @default_locale ||= fetch("locale")
+    end
+
+    def content_dirname
+      @content_dirname ||= fetch("content_dir")
+    end
+
+    def mode
+      @mode ||= begin
+        value = config["mode"]
+        value == "auto" ? value : DEFAULT_CONFIG["mode"]
       end
     end
 
@@ -57,10 +110,7 @@ module Jekyll
     end
 
     def locales_dir
-      @locales_dir ||= begin
-        value = config["locales_dir"]
-        value.to_s.empty? ? "locales" : value
-      end
+      @locales_dir ||= fetch("data_dir")
     end
 
     def locale_data
@@ -72,5 +122,18 @@ module Jekyll
         Jekyll::Utils.snake_case_keys(ldata)
       end
     end
+
+    def fetch(key)
+      value   = config[key]
+      default = DEFAULT_CONFIG[key]
+      return default unless value.class == default.class
+      return default if value.to_s.empty?
+
+      value
+    end
+
+    def exclusion_regex
+      @exclusion_regex ||= Regexp.new("\\A(?:#{Regexp.union(Array(config["exclude_set"]))})")
+    end
   end
 end

data/lib/jekyll/locale/mixins/helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Locale::Helper
+    attr_reader :canon, :relative_path
+
+    def setup_hreflangs?
+      true
+    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 permalink
+      canon_link = super
+      File.join(locale, canon_link) if canon_link
+    end
+
+    def inspect
+      "#<#{self.class} @canon=#{canon.inspect} @locale=#{locale.inspect}>"
+    end
+    alias_method :to_s, :inspect
+
+    private
+
+    def setup(canon, locale)
+      @locale = locale
+      @canon = canon
+      @site = canon.site
+      @extname = canon.extname
+      @relative_path = canon.relative_path
+      @path = site.in_source_dir(site.locale_handler.content_dirname, locale, relative_path)
+    end
+
+    def configure_data
+      Jekyll::Utils.deep_merge_hashes(canon.data, @data)
+    end
+  end
+end

data/lib/jekyll/locale/mixins/support.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module Locale::Support
+    attr_reader :locale
+
+    def setup_hreflangs?
+      false
+    end
+
+    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
+end

data/lib/jekyll/locale/page.rb

@@ -2,39 +2,20 @@
 
 module Jekyll
   class Locale::Page < Page
-    extend Forwardable
-
-    attr_reader    :canon, :locale
-    attr_accessor  :data, :content, :output
-
-    def_delegators :@canon, :site, :extname, :relative_path
+    include Locale::Helper
 
     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
+      setup(canon, locale)
+      @dir, @name = File.split(relative_path)
+      @dir  = "" if @dir == "."
+      @base = site.source
+      process(@name)
+      read_yaml(@dir, @name)
+      configure_data
     end
 
-    def inspect
-      "#<#{self.class} @canon=#{canon.inspect} @locale=#{locale.inspect}>"
+    def template
+      @template ||= File.join("", locale, super)
     end
-    alias_method :to_s, :inspect
   end
 end

data/lib/jekyll/locale/version.rb

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

data/lib/jekyll-locale.rb

@@ -2,47 +2,40 @@
 
 module Jekyll
   module Locale
-    autoload :Drop,    "jekyll/locale/drop"
-    autoload :Page,    "jekyll/locale/page"
-    autoload :Handler, "jekyll/locale/handler"
+    autoload :Drop,     "jekyll/locale/drop"
+    autoload :Document, "jekyll/locale/document"
+    autoload :AutoPage, "jekyll/locale/auto_page"
+    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"
 
+require_relative "jekyll/locale/mixins/support"
+require_relative "jekyll/locale/mixins/helper"
+
+# Enhance Jekyll::Page and Jekyll::Document classes
+[Jekyll::Page, Jekyll::Document].each do |klass|
+  klass.include Jekyll::Locale::Support
+end
+
+# Load Locale::Generator if requested
 Jekyll::Hooks.register :site, :after_reset do |site|
-  site.locale_handler.reset
+  handler = site.locale_handler
+  handler.reset
+  require_relative "jekyll/locale/generator" if handler.mode == "auto"
+end
+
+Jekyll::Hooks.register :site, :post_read do |site|
+  handler = site.locale_handler
+  handler.read unless handler.mode == "auto"
 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)
+  document.setup_hreflangs if document.setup_hreflangs?
   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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ashwin Maroli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-24 00:00:00.000000000 Z
+date: 2018-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -34,10 +34,14 @@ files:
 - LICENSE.txt
 - README.md
 - lib/jekyll-locale.rb
+- lib/jekyll/locale/auto_page.rb
+- lib/jekyll/locale/document.rb
 - lib/jekyll/locale/drop.rb
+- lib/jekyll/locale/generator.rb
 - lib/jekyll/locale/handler.rb
+- lib/jekyll/locale/mixins/helper.rb
+- lib/jekyll/locale/mixins/support.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

data/lib/jekyll/locale/page_generator.rb

@@ -1,30 +0,0 @@
-# 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