Class: Jekyll::L10n::LocalizedPage

Inherits:
Page
  • Object
show all
Defined in:
lib/jekyll-l10n/jekyll/localized_page.rb

Overview

Localized Page - Represents a Jekyll page in a specific locale

LocalizedPage extends Jekyll::Page to represent a page content variant for a specific language. It inherits content and metadata from the source page while maintaining locale-specific URLs and data attributes. The locale is included as a URL prefix (e.g., /es/path/to/page/).

Key responsibilities:

  • Maintain both original and localized URLs and paths
  • Inherit content and front matter from source page
  • Set locale and lang attributes for Liquid templates
  • Generate locale-prefixed output paths

During the post-render phase, LocalizedPage content is translated using translations from PO files. The translation process happens in the post_render Jekyll hook.

Examples:

Creating a localized page variant

page = LocalizedPage.new(site: site, base: site.source, dir: '/es',
                          page: source_page, locale: 'es')
# Resulting URL: /es/path/to/page/
# Resulting locale: es

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(site:, base:, dir:, page:, locale:) ⇒ LocalizedPage

Note:

All parameters are keyword arguments and must be passed by name

Initialize a new localized page variant

Creates a page instance that represents the given page in a specific locale. Copies all essential attributes from the source page and sets up locale-specific metadata and URLs.

Note: This method copies the @output attribute from the source page. In production, by Jekyll during the Render phase. This initialization ensures LocalizedPage has the same @output as its source page, which may be useful in test scenarios or if LocalizedPage is created after rendering.

Parameters:

  • site (Jekyll::Site) —

    (keyword) The Jekyll site object

  • base (String) —

    (keyword) The base directory (typically site.source)

  • dir (String) —

    (keyword) The directory path (will be prefixed with locale, e.g., '/es/path')

  • page (Jekyll::Page) —

    (keyword) The source page to localize

  • locale (String) —

    (keyword) The canonical locale code (e.g., 'es', 'pt_BR', 'zh_CN')



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 64

def initialize(site:, base:, dir:, page:, locale:)
  @site = site
  @base = base
  @dir = dir
  @name = page.name
  @ext = page.ext
  @output_ext = page.output_ext

  @locale = locale
  @lang = locale
  @original_url = page.url
  @original_page = page
  @path = page.path
  @relative_path = page.relative_path
  @content = page.content
  @output = page.output

  setup_localized_data(page, locale)
end

Instance Attribute Details

#lang ⇒ String

Alias for locale, used in Liquid templates

Returns:

  • (String) 


42
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 42

attr_accessor :locale, :lang, :original_page, :original_url

#locale ⇒ String

The canonical (POSIX/gettext) locale code for this page variant (e.g., 'es', 'pt_BR')

Returns:

  • (String) 


42
43
44
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 42

def locale
  @locale
end

#original_page ⇒ Jekyll::Page

Reference to the source page before localization

Returns:

  • (Jekyll::Page) 


42
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 42

attr_accessor :locale, :lang, :original_page, :original_url

#original_url ⇒ String

The URL of the source page before locale prefix was added

Returns:

  • (String) 


42
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 42

attr_accessor :locale, :lang, :original_page, :original_url

Instance Method Details

#destination(dest = nil) ⇒ String

Get the destination file path for this localized page

Computes the full file system path where this page's content will be written. For HTML pages with URL '/es-ES/path/to/page/', this returns 'dest/es-ES/path/to/page/index.html'. For assets with URL '/es-ES/assets/style.css', this returns 'dest/es-ES/assets/style.css'.

Parameters:

  • dest (String, nil) (defaults to: nil) —

    The destination directory (defaults to nil, which uses site config destination)

Returns:

  • (String) —

    The full file system path for the output file



128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 128

def destination(dest = nil)
  dest ||= @site.config['destination']
  url_path = url

  # Only use index.html for HTML pages
  if @output_ext == '.html'
    url_path += '/' unless url_path.end_with?('/')
    "#{dest}#{url_path}index.html"
  else
    # For assets, preserve the file extension
    "#{dest}#{url_path}"
  end
end

#to_liquid ⇒ Hash<String, Object>

Convert this localized page to Liquid template data

Overrides Jekyll::Page's to_liquid to include locale and lang in template context. The url key contains the BCP 47 hyphenated form; locale and lang remain canonical. This makes the page's locale available to Liquid templates for conditional rendering and URL generation.

Returns:

  • (Hash<String, Object>) —

    Hash of page data for Liquid templates, including locale



150
151
152
153
154
155
156
157
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 150

def to_liquid
  computed_url = url
  result = super
  result['url'] = computed_url
  result['locale'] = @locale
  result['lang'] = @lang
  result
end

#url ⇒ String

Get the full URL for this localized page

Returns the page's URL with a locale prefix in BCP 47 hyphenated form. For example, if the source page URL is '/path/to/page/', this returns '/es-ES/path/to/page/' for locale 'es_ES'. For HTML pages, URLs end with a trailing slash. For assets, the file extension is preserved.

Returns:

  • (String) —

    The locale-prefixed URL with optional trailing slash (e.g., '/es-ES/path/to/page/' or '/es-ES/assets/style.css')



109
110
111
112
113
114
115
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 109

def url
  url_locale = LocaleUrlFormatter.to_url_segment(@locale)
  url = "/#{url_locale}#{@original_url}"
  # Only add trailing slash for directory URLs (no file extension)
  url += '/' unless url.end_with?('/') || url =~ /\.[a-zA-Z0-9]+$/
  url
end

#url_placeholders ⇒ Hash<Symbol, String>

Get the URL placeholder substitutions for this localized page

Overrides Jekyll::Page's url_placeholders to include the locale prefix in path generation. The locale segment is converted to BCP 47 hyphenated form for use in URLs. This ensures that Jekyll's permalink logic respects the locale prefix.

Returns:

  • (Hash<Symbol, String>) —

    Hash of placeholders with locale-prefixed path



91
92
93
94
95
96
97
98
 
# File 'lib/jekyll-l10n/jekyll/localized_page.rb', line 91

def url_placeholders
  placeholders = super
  if placeholders[:path]
    url_locale = LocaleUrlFormatter.to_url_segment(@locale)
    placeholders[:path] = "/#{url_locale}#{placeholders[:path]}"
  end
  placeholders
end