Module: Jekyll::L10n::UrlFilter

Defined in:
lib/jekyll-l10n/jekyll/url_filter.rb

Overview

URL Filter - Liquid filters for locale-aware URL generation

Provides Liquid filters for use in Jekyll templates to generate locale-prefixed URLs. These filters are automatically registered with Liquid during plugin initialization.

This module is designed to be included in Liquid::Template’s filter registry, making the filters available in all Jekyll templates.

Key responsibilities:

  • Generate locale-prefixed URLs for links

  • Switch between locale variants of the same page

  • Validate locales against site configuration

  • Handle edge cases (external URLs, anchors, protocols)

Examples:

Usage in Jekyll Liquid templates

<!-- Add locale prefix to URL -->
<a href="{{ '/about/' | locale_url: 'es' }}">Acerca de</a>

<!-- Switch to different locale variant -->
<a href="{{ page.url | switch_locale_url: 'fr' }}">Français</a>

See Also:

Instance Method Summary collapse

Instance Method Details

#locale_url(url, locale = nil) ⇒ String

Generate a locale-prefixed URL for the given URL and locale

Adds a locale prefix to the given URL, making it suitable for use in locale-specific links. For example, ‘/about/’ becomes ‘/es/about/’ for locale ‘es’. The filter handles various edge cases and only applies the prefix when appropriate.

The method performs several checks to determine if prefixing is appropriate:

  • Invalid locale codes (nil, empty, or ‘en’) are skipped

  • URLs already localized are not prefixed again

  • External URLs, anchors, and relative paths are not modified

Examples:

<!-- Explicit locale -->
{{ '/about/' | locale_url: 'es' }}  # => '/es/about/'

<!-- Current page's locale -->
{{ '/about/' | locale_url }}  # => '/es/about/' (if page locale is 'es')

Parameters:

  • url (String) —

    The URL to prefix (e.g., ‘/about/’, ‘/path/to/page/’)

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

    The locale code (e.g., ‘es’, ‘pt_BR’). Defaults to nil (uses current page’s locale). If nil, uses page’s locale from context.

Returns:

  • (String) —

    The locale-prefixed URL, or original URL if prefixing is not appropriate



52
53
54
55
56
57
 
# File 'lib/jekyll-l10n/jekyll/url_filter.rb', line 52

def locale_url(url, locale = nil)
  locale ||= current_locale
  return url if should_skip?(url, locale)

  "/#{locale}#{url}"
end

#switch_locale_url(url, target_locale) ⇒ String

Generate a URL for the given locale variant of the current page

Switches the current URL to a different locale variant. For example, if the current page is ‘/es/about/’, calling this with ‘fr’ returns ‘/fr/about/’. This is useful for building language switcher menus.

This filter first extracts the base URL (without locale prefix) from the given URL, then applies the target locale using the standard locale_url logic.

Examples:

<!-- Current page is /es/about/, switch to French -->
{{ page.url | switch_locale_url: 'fr' }}  # => '/fr/about/'

<!-- Build a language switcher -->
<a href="{{ page.url | switch_locale_url: 'es' }}">Español</a>
<a href="{{ page.url | switch_locale_url: 'fr' }}">Français</a>
<a href="{{ page.url | switch_locale_url: 'pt' }}">Português</a>

Parameters:

  • url (String) —

    The current URL (may or may not have a locale prefix)

  • target_locale (String) —

    The target locale code (e.g., ‘es’, ‘fr’, ‘pt_BR’)

Returns:

  • (String) —

    The URL for the target locale, or original URL if locale is invalid



79
80
81
82
83
84
85
86
87
88
 
# File 'lib/jekyll-l10n/jekyll/url_filter.rb', line 79

def switch_locale_url(url, target_locale)
  # Validate target locale is configured
  return url unless valid_target_locale?(target_locale)

  # Get base URL without locale prefix
  base_url_value = base_url(url)

  # Apply target locale using existing locale_url logic
  locale_url(base_url_value, target_locale)
end