jekyll-l10n 1.6.5 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86534914442108c4e4abb039b16d3b8de6b13617c3f82526e005cdb2f94e673c
-  data.tar.gz: 9753110b3e0523464f84e89163dd6ab4db3946adc7bf7082467d245561272e9e
+  metadata.gz: f6934d1bf9c34ff4b1806a1b3dde6c19398ee10d261a7a3aa7925716e63f556f
+  data.tar.gz: fde2a5801b9558384d7d6b0f9854526af3d5759d567cddce5aaa94c9f0873c78
 SHA512:
-  metadata.gz: 60b30c77383e6b28c0974af6ac666abe5405473a4eac4ba83b3d1d681f7cb22d997ef6af7b584c37d22895a36e5669fd8670cfb330d862b59bae53ee047cebce
-  data.tar.gz: 91748739e07c2f5ee60cedd5e4693cb926aa0c953015d7bf2afb3d47b2fc74c10af99be5d0bca3184ca33ef1e9088c93bedda663aa1c10a0b95abd0b446b89ef
+  metadata.gz: 5fd0cf1f00fdd2a0b986540f4c8aeefd2cff50fac3122b6285a92a9f45b317042b28d8f72d6eadadbdc90e1c283ad792b18edd681000799541b53a75dbdbef92
+  data.tar.gz: ec515247b53374ca812d0195815150276ce39c078356383f667a926ef313ec50fa909b316c90e03f85c3a1ede8b753f399c63542e290b3eda12035cf9b56973a

data/lib/jekyll-l10n/constants.rb

@@ -27,9 +27,13 @@ module Jekyll
       # Regex fragment for matching locale codes in URL path segments.
       # Accepts both underscore ('pt_BR') and hyphen ('zh-CN') subtag separators,
       # unlike LOCALE_PATTERN which only accepts underscore (strict validation form).
+      # Region subtag is case-tolerant ([a-zA-Z]{2}): generated URLs are lowercase
+      # (see LocaleUrlFormatter), but this fragment also detects already-localized
+      # prefixes in hand-authored hrefs or pre-existing uppercase URLs, so it must
+      # still recognize uppercase regions.
       # Compose into full path patterns rather than using standalone.
       # @return [String]
-      LOCALE_CODE_SEGMENT = '[a-z]{2}(?:[_-][A-Z]{2})?'
+      LOCALE_CODE_SEGMENT = '[a-z]{2}(?:[_-][a-zA-Z]{2})?'
 
       # ## Translation Fallback Modes
 

data/lib/jekyll-l10n/extraction/config_loader.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative '../utils/page_locales_config'
+require_relative '../utils/locale_url_formatter'
+require_relative '../utils/site_config_accessor'
 
 module Jekyll
   module L10n
@@ -84,18 +86,19 @@ module Jekyll
       #
       # Localized pages are generated copies in locale subdirectories that
       # shouldn't be re-extracted (extraction happens on original pages only).
+      # Since commit 3d2d4cd, country-subtag locales (e.g. es_ES) are written
+      # to BCP 47 hyphenated, lowercased URL directories (e.g. es-es/). Each
+      # configured locale is normalized through LocaleUrlFormatter.to_url_segment
+      # before comparison so both language-only (es) and country-subtag
+      # (es_ES → es-es) locales are correctly recognized.
       #
       # @param file_path [String] Path to file to check
       # @return [Boolean] True if file is in a locale subdirectory
       def skip_localized_page?(file_path)
         relative_path = file_path.sub(@dest, '')
 
-        all_locales = @site.pages.map do |p|
-          p.data.dig('with_locales_data', 'locales') || []
-        end
-        all_locales.flatten!
-        all_locales.uniq!
-        all_locales.any? { |locale| relative_path.start_with?("/#{locale}/") }
+        all_locales = SiteConfigAccessor.all_configured_locales(@site)
+        all_locales.any? { |locale| relative_path.start_with?("/#{LocaleUrlFormatter.to_url_segment(locale)}/") }
       end
 
       # Extract CSS selectors for element exclusion from configuration.

data/lib/jekyll-l10n/extraction/result_saver.rb

@@ -68,12 +68,17 @@ module Jekyll
       # Called once per build (from Extractor.extract_site) rather than per page,
       # reducing disk I/O and fuzzy-matching passes from O(pages) to O(1).
       #
+      # Uses the union of all locales configured anywhere on the site (site-wide
+      # defaults plus any page-level front-matter overrides) so that page-only
+      # locales (e.g. es_ES declared only in page front matter) are included in the
+      # compendium merge, not left as orphaned per-page directories.
+      #
       # @return [void]
       def finalize_compendia
         return unless @site_config.update_compendium?
 
         po_manager = PoFileManager.new(@site, @site_config.locales_dir)
-        CompendiumMerger.new(@site).merge_compendia(po_manager, @site_config)
+        CompendiumMerger.new(@site).merge_compendia(po_manager, merge_config)
       end
 
       # Translate compendia using LibreTranslate.
@@ -100,7 +105,21 @@ module Jekyll
         po_files_created
       end
 
+      # Build a PageLocalesConfig whose locale list is the union of site-wide
+      # defaults and every page-level front-matter locale override.
+      #
+      # All other site-wide settings (locales_dir, extraction, translation,
+      # logging, etc.) are preserved unchanged; only the locale list is widened.
+      #
+      # @return [PageLocalesConfig]
+      def merge_config
+        all_locales = SiteConfigAccessor.all_configured_locales(@site)
+        merged_data = (@site_config.data['with_locales_data'] || {}).merge('locales' => all_locales)
+        PageLocalesConfig.new({ 'with_locales_data' => merged_data })
+      end
+
       private :save_po_files
+      private :merge_config
     end
   end
 end

data/lib/jekyll-l10n/jekyll/generator.rb

@@ -2,6 +2,7 @@
 
 require_relative '../constants'
 require_relative 'regeneration_checker'
+require_relative '../utils/locale_url_formatter'
 
 module Jekyll
   module L10n
@@ -112,7 +113,7 @@ module Jekyll
       end
 
       def create_localized_page(site, page, locale)
-        new_dir = "/#{locale}#{page.dir}"
+        new_dir = "/#{LocaleUrlFormatter.to_url_segment(locale)}#{page.dir}"
         LocalizedPage.new(site: site, base: site.source, dir: new_dir, page: page,
                           locale: locale)
       end

data/lib/jekyll-l10n/jekyll/localized_page.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../utils/locale_url_formatter'
+
 module Jekyll
   module L10n
     # Localized Page - Represents a Jekyll page in a specific locale
@@ -26,7 +28,7 @@ module Jekyll
     #
     class LocalizedPage < Jekyll::Page
       # @!attribute [rw] locale
-      #   The BCP 47 locale code for this page variant (e.g., 'es', 'pt_BR')
+      #   The canonical (POSIX/gettext) locale code for this page variant (e.g., 'es', 'pt_BR')
       #   @return [String]
       # @!attribute [rw] lang
       #   Alias for locale, used in Liquid templates
@@ -56,7 +58,7 @@ module Jekyll
       # @param dir [String] (keyword) The directory path (will be prefixed with locale,
       #   e.g., '/es/path')
       # @param page [Jekyll::Page] (keyword) The source page to localize
-      # @param locale [String] (keyword) The BCP 47 locale code (e.g., 'es', 'pt_BR', 'zh_CN')
+      # @param locale [String] (keyword) The canonical locale code (e.g., 'es', 'pt_BR', 'zh_CN')
       # @return [LocalizedPage] A new localized page instance
       # @note All parameters are keyword arguments and must be passed by name
       def initialize(site:, base:, dir:, page:, locale:)
@@ -82,25 +84,31 @@ module Jekyll
       # 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.
       #
       # @return [Hash<Symbol, String>] Hash of placeholders with locale-prefixed path
       def url_placeholders
         placeholders = super
-        placeholders[:path] = "/#{@locale}#{placeholders[:path]}" if placeholders[:path]
+        if placeholders[:path]
+          url_locale = LocaleUrlFormatter.to_url_segment(@locale)
+          placeholders[:path] = "/#{url_locale}#{placeholders[:path]}"
+        end
         placeholders
       end
 
       # Get the full URL for this localized page
       #
-      # Returns the page's URL with a locale prefix. For example, if the source page URL is
-      # '/path/to/page/', this returns '/es/path/to/page/' for locale 'es'.
+      # 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.
       #
       # @return [String] The locale-prefixed URL with optional trailing slash
-      #   (e.g., '/es/path/to/page/' or '/es/assets/style.css')
+      #   (e.g., '/es-ES/path/to/page/' or '/es-ES/assets/style.css')
       def url
-        url = "/#{@locale}#{@original_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
@@ -109,8 +117,10 @@ module Jekyll
       # 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/path/to/page/', this returns 'dest/es/path/to/page/index.html'.
-      # For assets with URL '/es/assets/style.css', this returns 'dest/es/assets/style.css'.
+      # 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'.
       #
       # @param dest [String, nil] The destination directory (defaults to nil, which uses
       #   site config destination)
@@ -132,6 +142,7 @@ module Jekyll
       # 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.
       #

data/lib/jekyll-l10n/jekyll/regeneration_checker.rb

@@ -2,6 +2,7 @@
 
 require_relative '../utils/site_config_accessor'
 require_relative '../po_file/path_builder'
+require_relative '../utils/locale_url_formatter'
 
 module Jekyll
   module L10n
@@ -84,8 +85,10 @@ module Jekyll
       end
 
       def dest_path(page, locale)
-        # Replicate LocalizedPage destination logic without instantiation
-        url = "/#{locale}#{page.url.chomp('/')}/"
+        # Replicate LocalizedPage destination logic without instantiation.
+        # Uses BCP 47 hyphenated locale segment to match LocalizedPage#destination output.
+        url_locale = LocaleUrlFormatter.to_url_segment(locale)
+        url = "/#{url_locale}#{page.url.chomp('/')}/"
         "#{@destination}#{url}index.html"
       end
 

data/lib/jekyll-l10n/jekyll/url_filter.rb

@@ -3,6 +3,8 @@
 require 'liquid'
 require_relative '../constants'
 require_relative '../utils/error_handler'
+require_relative '../utils/locale_name_resolver'
+require_relative '../utils/locale_url_formatter'
 
 module Jekyll
   module L10n
@@ -15,25 +17,30 @@ module Jekyll
     # the filters available in all Jekyll templates.
     #
     # Key responsibilities:
-    # - Generate locale-prefixed URLs for links
+    # - Generate locale-prefixed URLs in BCP 47 hyphenated form
     # - Switch between locale variants of the same page
-    # - Validate locales against site configuration
+    # - Build structured locale-switcher menu data
+    # - Validate locales against site configuration (with form normalization)
     # - Handle edge cases (external URLs, anchors, protocols)
     #
     # @example Usage in Jekyll Liquid templates
     #   <!-- Add locale prefix to URL -->
-    #   <a href="{{ '/about/' | locale_url: 'es' }}">Acerca de</a>
+    #   <a href="{{ '/about/' | locale_url: 'es_ES' }}">Acerca de</a>
+    #   <!-- Produces: /es-ES/about/ -->
     #
     #   <!-- Switch to different locale variant -->
     #   <a href="{{ page.url | switch_locale_url: 'fr' }}">Français</a>
     #
+    #   <!-- Build a language-switcher menu -->
+    #   {% assign menu = page.url | locale_menu %}
+    #
     # @see Jekyll::L10n for filter registration (line 218 in lib/jekyll-l10n.rb)
     #
     module UrlFilter
       # 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
+      # Adds a locale prefix in BCP 47 hyphenated form to the given URL. For example,
+      # '/about/' becomes '/es-ES/about/' for locale 'es_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:
@@ -42,12 +49,13 @@ module Jekyll
       # - External URLs, anchors, and relative paths are not modified
       #
       # @param url [String] The URL to prefix (e.g., '/about/', '/path/to/page/')
-      # @param locale [String, nil] The locale code (e.g., 'es', 'pt_BR'). Defaults to nil
+      # @param locale [String, nil] The locale code (e.g., 'es_ES', 'pt_BR'). Defaults to nil
       #   (uses current page's locale). If nil, uses page's locale from context.
-      # @return [String] The locale-prefixed URL, or original URL if prefixing is not appropriate
+      # @return [String] The locale-prefixed URL in BCP 47 form, or original URL if
+      #   prefixing is not appropriate
       # @example
-      #   <!-- Explicit locale -->
-      #   {{ '/about/' | locale_url: 'es' }}  # => '/es/about/'
+      #   <!-- Explicit underscore locale converted to hyphen in URL -->
+      #   {{ '/about/' | locale_url: 'es_ES' }}  # => '/es-ES/about/'
       #
       #   <!-- Current page's locale -->
       #   {{ '/about/' | locale_url }}  # => '/es/about/' (if page locale is 'es')
@@ -55,29 +63,29 @@ module Jekyll
         locale ||= current_locale
         return url if should_skip?(url, locale)
 
-        "/#{locale}#{url}"
+        url_segment = LocaleUrlFormatter.to_url_segment(locale)
+        "/#{url_segment}#{url}"
       end
 
       # 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
+      # page is '/es-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.
       #
       # @param url [String] The current URL (may or may not have a locale prefix)
-      # @param target_locale [String] The target locale code (e.g., 'es', 'fr', 'pt_BR')
+      # @param target_locale [String] The target locale code (e.g., 'es_ES', 'fr', 'pt_BR')
       # @return [String] The URL for the target locale, or original URL if locale is invalid
       # @example
-      #   <!-- Current page is /es/about/, switch to French -->
+      #   <!-- Current page is /es-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: 'es_ES' }}">Español (España)</a>
       #   <a href="{{ page.url | switch_locale_url: 'fr' }}">Français</a>
-      #   <a href="{{ page.url | switch_locale_url: 'pt' }}">Português</a>
       def switch_locale_url(url, target_locale)
         # Validate target locale is configured
         return url unless valid_target_locale?(target_locale)
@@ -89,6 +97,37 @@ module Jekyll
         locale_url(base_url_value, target_locale)
       end
 
+      # Build the full locale-switcher menu for the current page.
+      #
+      # Returns one entry per locale available to the current page (via the
+      # existing #configured_locales resolution — site-wide with_locales_data.locales
+      # config, or a page-level front-matter override — always including English
+      # even if not explicitly configured). Each entry carries everything a theme
+      # needs to render a menu item with zero locale-specific logic of its own:
+      # a display name, a switch-target URL, and whether it's the page's current
+      # locale.
+      #
+      # @param url [String] The current page's URL (e.g. page.url)
+      # @return [Array<Hash>] Array of { 'code', 'name', 'url', 'current' } hashes,
+      #   one per locale. +code+ is the canonical underscore form (e.g. "es_ES"),
+      #   +name+ is the ISO-resolved display name (e.g. "Spanish (Spain)"),
+      #   +url+ is what {#switch_locale_url} produces for that locale, and
+      #   +current+ is +true+ only for the locale matching the page's own locale.
+      # @example
+      #   {{ page.url | locale_menu }}
+      #   # => [{"code"=>"en","name"=>"English","url"=>"/about/","current"=>false},
+      #   #     {"code"=>"es_ES","name"=>"Spanish (Spain)","url"=>"/es-ES/about/","current"=>true}]
+      def locale_menu(url)
+        menu_locales.map do |locale|
+          {
+            'code' => locale,
+            'name' => LocaleNameResolver.resolve(locale),
+            'url' => switch_locale_url(url, locale),
+            'current' => locale == (current_locale || 'en')
+          }
+        end
+      end
+
       private
 
       def current_locale
@@ -96,7 +135,7 @@ module Jekyll
         return nil unless page
 
         if page.is_a?(Hash)
-          page.dig('data', 'locale')
+          page.dig('data', 'locale') || page['locale']
         else
           page&.data&.[]('locale')
         end
@@ -155,7 +194,11 @@ module Jekyll
 
         # Get configured locales from page or site config
         locales_config = configured_locales
-        locales_config.include?(locale)
+
+        # Normalize both the target locale and each configured locale to BCP 47 form
+        # before comparing, so 'es-ES' matches 'es_ES' and vice versa.
+        url_locale = LocaleUrlFormatter.to_url_segment(locale)
+        locales_config.any? { |l| LocaleUrlFormatter.to_url_segment(l) == url_locale }
       end
 
       def configured_locales
@@ -175,6 +218,18 @@ module Jekyll
         []
       end
 
+      # Locales for the menu: whatever #configured_locales resolves for the
+      # current page, always including English even if not explicitly listed
+      # (English pages never carry a locale prefix, but must still appear as a
+      # switch target).
+      #
+      # @return [Array<String>]
+      def menu_locales
+        locales = configured_locales.dup
+        locales.unshift('en') unless locales.include?('en')
+        locales
+      end
+
       def base_url(url)
         page = @context.registers[:page]
 

data/lib/jekyll-l10n/translation/libre_translator.rb

@@ -172,7 +172,7 @@ module Jekyll
 
           texts = [entry.msgid]
           translations = make_api_request(texts, target_locale)
-          entry.msgstr = translations[0] || ''
+          entry.msgstr = translations&.first || ''
         end
       rescue StandardError => e
         ErrorHandler.log_error('translate_batch', e)
@@ -225,6 +225,13 @@ module Jekyll
 
       def handle_api_response(response)
         response_data = JSON.parse(response.body)
+
+        if response_data['error']
+          Jekyll.logger.warn 'Localization',
+                             "[LibreTranslator] API rejected request: #{response_data['error']}"
+          return nil
+        end
+
         translated = response_data['translatedText']
         translation_str = translated.is_a?(Array) ? translated.inspect : translated
         Jekyll.logger.debug 'Localization', "[LibreTranslator] Parsed translation: #{translation_str}"

data/lib/jekyll-l10n/utils/locale_name_resolver.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'locale/info'
+
+module Jekyll
+  module L10n
+    # Resolves a canonical locale code into a human-readable display name using
+    # ISO 639-1 language names and ISO 3166-1 country names from the +locale+ gem.
+    #
+    # Supported input forms:
+    # - Language-only: <tt>"es"</tt> → <tt>"Spanish"</tt>
+    # - Language + country subtag (POSIX underscore form): <tt>"es_ES"</tt> → <tt>"Spanish (Spain)"</tt>,
+    #   <tt>"pt_BR"</tt> → <tt>"Portuguese (Brazil)"</tt>
+    #
+    # Falls back to the raw code segment when the locale gem cannot resolve a
+    # language or region code. This is a defensive-only path — every locale that
+    # reaches this class from plugin-managed configuration has already passed
+    # +Constants::LOCALE_PATTERN+ validation, so unknown codes are not expected
+    # in normal operation.
+    #
+    # @example Language-only codes
+    #   Jekyll::L10n::LocaleNameResolver.resolve('es')  # => "Spanish"
+    #   Jekyll::L10n::LocaleNameResolver.resolve('en')  # => "English"
+    #   Jekyll::L10n::LocaleNameResolver.resolve('pt')  # => "Portuguese"
+    #
+    # @example Country-subtag codes
+    #   Jekyll::L10n::LocaleNameResolver.resolve('es_ES')  # => "Spanish (Spain)"
+    #   Jekyll::L10n::LocaleNameResolver.resolve('pt_BR')  # => "Portuguese (Brazil)"
+    #
+    # @example Fallback for unresolvable codes (defensive)
+    #   Jekyll::L10n::LocaleNameResolver.resolve('xx')     # => "xx"
+    #   Jekyll::L10n::LocaleNameResolver.resolve('xx_YY')  # => "xx (YY)"
+    class LocaleNameResolver
+      # Resolve a canonical locale code to a human-readable display name.
+      #
+      # @param locale [String, nil] The locale code to resolve (e.g. <tt>"es"</tt>,
+      #   <tt>"es_ES"</tt>, <tt>"pt_BR"</tt>). +nil+ or empty string returns an
+      #   empty string without raising.
+      # @return [String] The resolved display name, or the raw code segment(s) if
+      #   the locale gem cannot resolve either part.
+      def self.resolve(locale)
+        language_code, country_code = locale.to_s.split('_', 2)
+        language_name = Locale::Info.get_language(language_code)&.name || language_code
+        return language_name unless country_code
+
+        country_name = Locale::Info.get_region(country_code)&.name || country_code
+        "#{language_name} (#{country_name})"
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/utils/locale_url_formatter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module L10n
+    # Converts a canonical (gettext/POSIX-style) locale identifier, e.g. "es_ES",
+    # into the BCP 47 form used in generated URLs and hrefs, e.g. "es-es".
+    # Lowercased per RFC 5646 ss2.1.1 (subtag case carries no meaning; this
+    # is a display-convention choice, not a standard requirement). Idempotent.
+    class LocaleUrlFormatter
+      def self.to_url_segment(locale)
+        locale.to_s.tr('_', '-').downcase
+      end
+    end
+  end
+end

data/lib/jekyll-l10n/utils/page_locales_config.rb

@@ -17,7 +17,7 @@ module Jekyll
     #
     # Key responsibilities:
     # - Parse `with_locales_data` from page front matter
-    # - Validate locale codes against ISO 639-1/2 format
+    # - Validate locale codes against ISO 639-1 (with optional ISO 3166-1 alpha-2 country) format
     # - Validate LibreTranslate configuration when enabled
     # - Provide getter methods with sensible defaults
     # - Raise detailed validation errors for invalid configurations
@@ -87,7 +87,8 @@ module Jekyll
       # Get the list of locales configured for this page
       #
       # Returns the locales specified in `with_locales_data.locales`, or an empty array
-      # if not configured. All returned locales are guaranteed to match ISO 639-1/2 format.
+      # if not configured. All returned locales are guaranteed to match ISO 639-1 format,
+      # optionally suffixed with an ISO 3166-1 alpha-2 country code.
       #
       # @return [Array<String>] BCP 47 locale codes (e.g., ['es', 'fr', 'pt_BR'])
       def locales
@@ -307,7 +308,7 @@ module Jekyll
         <<~ERROR
           Invalid locale codes in #{@page_path}: #{invalid_codes.join(', ')}
 
-          Expected ISO 639-1/2 format (e.g., 'es', 'fr', 'pt_BR')
+          Expected ISO 639-1 language code, optionally with ISO 3166-1 alpha-2 country (e.g., 'es', 'fr', 'pt_BR')
           Valid pattern: ^[a-z]{2}(_[A-Z]{2})?$
 
           Common mistakes:
@@ -328,7 +329,7 @@ module Jekyll
                 'LibreTranslate is enabled but libretranslate_api_url is not configured'
         end
 
-        # Validate source locale format (ISO 639-1/2)
+        # Validate source locale format (ISO 639-1, optionally with ISO 3166-1 alpha-2 country)
         unless LOCALE_PATTERN.match?(libretranslate_source_locale)
           raise Jekyll::Errors::InvalidConfigurationError,
                 "Invalid libretranslate_source_locale: #{libretranslate_source_locale}"

data/lib/jekyll-l10n/utils/site_config_accessor.rb

@@ -10,12 +10,14 @@ module Jekyll
     #
     # Key responsibilities:
     # * Extract localization data from site configuration
+    # * Compute the union of all configured locales across site and page front matter
     # * Access site source directory
     # * Access site destination directory
     # * Handle both Jekyll site objects and hash-based doubles
     #
     # @example
     #   locales_data = SiteConfigAccessor.extract_locales_data(site)
+    #   all_locales  = SiteConfigAccessor.all_configured_locales(site)
     #   source = SiteConfigAccessor.source(site)
     #   dest = SiteConfigAccessor.dest(site)
     class SiteConfigAccessor
@@ -33,6 +35,27 @@ module Jekyll
         entry&.dig('values', 'with_locales_data') || {}
       end
 
+      # Compute the union of all locales configured anywhere on the site.
+      #
+      # Combines locales from two sources:
+      # - The site-wide `with_locales_data.locales` default (from `_config.yml`)
+      # - Any page-level `with_locales_data.locales` front-matter override, since
+      #   a page-level override replaces the site default for that page rather than
+      #   inheriting it, so page scanning alone misses site-wide locales when few
+      #   or no ordinary pages are present.
+      #
+      # This lets callers discover locales that exist only as a page-level override,
+      # not declared in site config, while also retaining all site-wide locales.
+      #
+      # @param site [Jekyll::Site, Hash] Jekyll site object or hash double
+      # @return [Array<String>] Unique locale codes configured anywhere on the site
+      def self.all_configured_locales(site)
+        site_wide_locales = extract_locales_data(site)['locales'] || []
+        pages = site.is_a?(Hash) ? site['pages'] : site.pages
+        page_locales = pages.flat_map { |p| p.data.dig('with_locales_data', 'locales') || [] }
+        (site_wide_locales + page_locales).uniq
+      end
+
       # Get the site source directory.
       #
       # @param site [Jekyll::Site, Hash] Jekyll site object or hash double

data/lib/jekyll-l10n/utils/url_transformer.rb

@@ -3,19 +3,21 @@
 require 'nokogiri'
 require_relative '../constants'
 require_relative 'html_parser'
+require_relative 'locale_url_formatter'
 
 module Jekyll
   module L10n
     # Transforms relative URLs in HTML to include locale prefixes.
     #
     # UrlTransformer modifies href attributes in links to prefix them with
-    # the target locale (e.g., /docs/page.html becomes /es/docs/page.html).
+    # the target locale in BCP 47 hyphenated form (e.g., /docs/page.html becomes
+    # /es-ES/docs/page.html for a canonical "es_ES" locale).
     # It preserves external links, anchors, mailto, tel links, and links
     # already containing locale prefixes. Skips English locale (default language).
     #
     # Key responsibilities:
     # * Identify relative links to transform
-    # * Add locale prefix to href values
+    # * Add locale prefix in BCP 47 form to href values
     # * Preserve external links and special URLs
     # * Skip already-localized URLs
     # * Handle baseurl paths correctly
@@ -23,20 +25,25 @@ module Jekyll
     #
     # @example
     #   html = '<a href="/docs/page.html">Link</a>'
-    #   transformed = UrlTransformer.transform(html, 'es', '/baseurl')
-    #   # Returns '<a href="/baseurl/es/docs/page.html">Link</a>'
+    #   transformed = UrlTransformer.transform(html, 'es_ES', '/baseurl')
+    #   # Returns '<a href="/baseurl/es-ES/docs/page.html">Link</a>'
     class UrlTransformer
       class << self
         # Transform all relative URLs in HTML to include locale prefix.
         #
-        # Parses HTML document, identifies relative links, adds locale prefix,
-        # removes auto-inserted meta tags, and returns transformed HTML.
+        # Parses HTML document, identifies relative links, adds locale prefix
+        # in BCP 47 hyphenated form, removes auto-inserted meta tags, and
+        # returns transformed HTML.
         #
         # @param html [String] HTML content with URLs to transform
-        # @param locale [String] Target locale code (e.g., 'es', 'fr')
+        # @param locale [String] Target locale code (e.g., 'es', 'es_ES', 'fr')
         # @param baseurl [String] Base URL for site (e.g., '/baseurl')
         # @return [String] HTML with locale-prefixed URLs
         def transform(html, locale, baseurl)
+          # Convert canonical locale to BCP 47 hyphenated form for URL usage.
+          # This is idempotent: already-hyphenated input is unchanged.
+          locale = LocaleUrlFormatter.to_url_segment(locale)
+
           return html if should_skip_transform?(locale)
 
           # Use Nokogiri::HTML to properly parse full HTML documents while preserving
@@ -58,10 +65,14 @@ module Jekyll
         # Useful when document is already parsed to avoid re-parsing.
         #
         # @param doc [Nokogiri::HTML::Document] Parsed HTML document
-        # @param locale [String] Target locale code
+        # @param locale [String] Target locale code (canonical or BCP 47 form)
         # @param baseurl [String] Base URL for site
         # @return [void]
         def transform_document(doc, locale, baseurl)
+          # Convert canonical locale to BCP 47 hyphenated form for URL usage.
+          # This is idempotent: already-hyphenated input is unchanged.
+          locale = LocaleUrlFormatter.to_url_segment(locale)
+
           return if should_skip_transform?(locale)
 
           doc.css('a[href]').each do |link|
@@ -142,7 +153,7 @@ module Jekyll
 
         def locale_prefix?(path)
           # Check if the path contains a locale code
-          # After stripping baseurl, this detects: /es/, /fr/, /pt_BR/, /zh-CN/, etc.
+          # After stripping baseurl, this detects: /es/, /fr/, /pt-BR/, /zh-CN/, etc.
           path.match?(%r{/#{Constants::LOCALE_CODE_SEGMENT}(?:/|$)}o)
         end
 

data/lib/jekyll-l10n/version.rb

@@ -6,6 +6,6 @@ module Jekyll
     # Regenerated alongside the gemspec on every `make jekyll-l10n.gemspec`
     # run (locally or in CI), so it always matches spec.version in the built
     # gem. Any hand edit is overwritten on the next run.
-    VERSION = '1.6.5'
+    VERSION = '1.7.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-l10n
 version: !ruby/object:Gem::Version
-  version: 1.6.5
+  version: 1.7.0
 platform: ruby
 authors:
 - Alain Reguera Delgado
@@ -49,6 +49,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: locale
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -256,6 +276,8 @@ files:
 - lib/jekyll-l10n/utils/html_elements.rb
 - lib/jekyll-l10n/utils/html_parser.rb
 - lib/jekyll-l10n/utils/html_text_utils.rb
+- lib/jekyll-l10n/utils/locale_name_resolver.rb
+- lib/jekyll-l10n/utils/locale_url_formatter.rb
 - lib/jekyll-l10n/utils/logger_formatter.rb
 - lib/jekyll-l10n/utils/page_locales_config.rb
 - lib/jekyll-l10n/utils/po_entry_converter.rb