jekyll-polyglot 1.11.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3ca341e67c10066675cb10c5ded127cf9126c5db547d2f3fdfc3d545c43bd6a
-  data.tar.gz: 32315c6551ac56da248adb7d465c130d8f0ec4f03a7d589eb5e2081c1a420821
+  metadata.gz: c41fff580d3b7b67c65668954a77168ecf5017f5c0ca7b3747bdcc67ddb7d8ed
+  data.tar.gz: 6666fb42d87a589c695229be0386cdd601511aee2115c6da472f2de3b829c8ef
 SHA512:
-  metadata.gz: b53d59e7090b20849d36cdfe6b54a6b0e40e40db839916f1df45c62f26b0ef541f43d30d88c3cbfcd0eb8e58ecc4e45b1f3ae1509cdd2aa0149aad4be41d9a95
-  data.tar.gz: 12a99dc155b5e4c7ba5f960e0267a90b547fa10576c9c3bf718784f139bf45b0da7554ac40e262b491aa113301eba5d1c16c2bb615fb901d26adf4cee90d0917
+  metadata.gz: 446131b28c107601f59f17e4d630c800c6c6b4c64290f00ecf417c407cfd1e3bb960f36a1994d84d7b438cd862d358216090556f198b89ab31a1f6043f842bc9
+  data.tar.gz: 4902c0e1a8de5060c667eade6806a3e3932eae52475c1a0ad1f4cb5fcb984086080e4c08bf7551eb923098c152e6a46ffe7d63475ec27f9acbe948bee48d8adb

data/README.md

@@ -28,7 +28,7 @@ In your `_config.yml` file, add the following preferences
 ```YAML
 languages: ["en", "sv", "de", "fr"]
 default_lang: "en"
-exclude_from_localization: ["javascript", "images", "css", "public", "sitemap"]
+exclude_from_localization: ["javascript", "images", "css", "public", "sitemap", "CNAME"]
 parallel_localization: true
 url: https://polyglot.untra.io
 ```
@@ -41,6 +41,16 @@ These configuration preferences indicate
 
 The optional `lang_from_path: true` option enables getting the page language from a filepath segment seperated by `/` or `.`, e.g `de/first-one.md`, or `_posts/zh_HK/use-second-segment.md` , if the lang frontmatter isn't defined.
 
+#### Netlify _redirects localization
+If you are deploying to Netlify and use a `_redirects` file, you can enable automatic localization of redirects:
+```yaml
+localize_redirects: true
+exclude_from_redirect_localization:
+  - /signin
+  - /app
+```
+See [Localizing Netlify _redirects](#localizing-netlify-_redirects) for more details.
+
 ## How To Use It
 When adding new posts and pages, add to the YAML front matter:
 ```
@@ -59,8 +69,7 @@ _posts/2010-03-01-salad-recipes-sv.md
 _posts/2010-03-01-salad-recipes-fr.md
 ```
 
-Organized names will generate consistent permalinks when the post is rendered, and Polyglot will know to build separate language versions of
-the website using only the files with the correct `lang` variable in the front matter.
+Organized names will generate consistent permalinks when the post is rendered, and Polyglot will know to build separate language versions of the website using only the files with the correct `lang` variable in the front matter.
 
 In short:
 * Be consistent with how you name and place your *posts* files
@@ -83,6 +92,19 @@ Sample code for meta link generation:
 ```
 
 
+#### Available and missing translations
+_New in 1.13.0_
+
+Polyglot exposes two arrays on every page describing its translation status:
+
+- `page.available_languages` — language codes that have an actual translation of this page.
+- `page.missing_languages` — languages that don't yet have a translation of this page.
+
+`missing_languages` is intentionally empty for pages that have no per-language translations at all: a single-source page falls back to identical content for every visitor, so there is nothing missing to flag. Only pages that already have *at least one* translations report the gaps.
+
+Combine with [`page.rendered_lang`](#detecting-fallback-pages-with-pagerendered_lang) to also flag fallback content on the page itself.
+
+
 #### Using different permalinks per language
 _New in 1.7.0_
 
@@ -114,12 +136,33 @@ Estos somos nosotros!
 Additionally, if you are also using the `jekyll-redirect-from` plugin, pages coordinated this way will automatically have redirects created between pages.
 So `/es/about` will automatically redirect to `/es/acerca-de` and `/acerca-de` can redirect to `/about`. If you use this approach, be sure to also employ a customized [redirect.html](https://github.com/untra/polyglot/blob/main/site/_layouts/redirect.html).
 
+As of version 1.12, Polyglot also properly supports `redirect_from` frontmatter across sublanguages. When you add redirect paths to pages in non-default languages, Polyglot will correctly scope those redirects to each language's prefix, preventing duplicate redirects and ensuring proper routing.
+
 #### Fallback Language Support
 Lets say you are building your website. You have an `/about/` page written in *english*, *german* and
 *swedish*. You are also supporting a *french* website, but you never designed a *french* version of your `/about/` page!
 
 No worries. Polyglot ensures the sitemap of your *english* site matches your *french* site, matches your *swedish* and *german* sites too. In this case, because you specified a `default_lang` variable in your `_config.yml`, all sites missing their languages' counterparts will fallback to your `default_lang`, so content is preserved across different languages of your site.
 
+#### Smart hreflang Generation
+
+Polyglot only generates `hreflang` tags for languages that have actual translations. This improves SEO correctness by not advertising language alternatives that don't actually exist.
+
+For example, if you have `/about.html` in English and Spanish but not French:
+- The English page gets `hreflang="en"`, `hreflang="es"`, and `hreflang="x-default"`
+- The Spanish page gets the same hreflang tags
+- No `hreflang="fr"` is generated, even though a French fallback page exists
+
+This behavior:
+- Generates pages for all languages (fallback content is still served)
+- Only advertises translations that actually exist via `hreflang` tags
+- Always includes `hreflang` for the default language and `x-default`
+
+Translation detection works via:
+1. **page_id matching**: Documents with the same `page_id` frontmatter are considered translations
+2. **permalink matching**: Documents with matching permalinks (and different `lang`) are considered translations
+3. **Searches both collections and standalone pages**: The `{% I18n_Headers %}` tag searches `site.collections` and `site.pages`
+
 ### Relativized Local Urls
 No need to meticulously manage anchor tags to link to your correct language. Polyglot modifies how pages get written to the site so your *french* links keep visitors on your *french* blog.
 ```md
@@ -158,6 +201,73 @@ becomes
 <p>Cliquez <a href="https://mywebsite.com/fr/">ici</a> pour aller à l'entrée du site.
 ```
 
+#### Canonical URL Handling
+
+For proper canonical URL handling on multilingual sites, we recommend using Polyglot's `{% I18n_Headers %}` tag for canonical URLs instead of jekyll-seo-tag's default canonical output. This provides intelligent canonical URL generation that:
+
+- Points to the translated URL for pages with actual translations
+- Points to the default language URL for fallback pages (pages without translations)
+- Properly handles the `page_id` and permalink matching for translation detection
+
+**Setup with jekyll-seo-tag:**
+
+If you're using [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag), you can disable its canonical output and let Polyglot handle it:
+
+```liquid
+{% seo canonical=false %}
+{% I18n_Headers %}
+```
+
+The `canonical=false` option is available in jekyll-seo-tag v2.9.0+
+
+**Fallback Canonical Behavior:**
+
+To have fallback pages (pages without translations) point their canonical URL to the default language version, add to your `_config.yml`:
+
+```yaml
+fallback_canonical_to_default_lang: true
+```
+
+With this option enabled:
+- Pages with actual translations: canonical points to the translated URL (e.g., `/es/sobre-nosotros/`)
+- Fallback pages (no translation): canonical points to the default language URL (e.g., `/about/` instead of `/es/about/`)
+
+This improves SEO by:
+- Preventing search engines from indexing duplicate fallback content under multiple language URLs
+- Consolidating SEO authority to the original content
+- Signaling to search engines which version is the authoritative source
+
+Note: `hreflang` URLs pointing to the default language or `x-default` are intentionally NOT relativized, as they should always point to the canonical language-specific URLs.
+
+### Localizing Netlify _redirects
+_New in 1.13.0_
+
+When using Polyglot with [Netlify](https://www.netlify.com/), redirect rules defined in a [Netlify `_redirects` file](https://docs.netlify.com/manage/routing/redirects/overview/#syntax-for-the-_redirects-file) will get relativized (e.g., `/github` becomes `/fr/github` on French pages). However the Netlify `_redirects` file only contains the redirect base paths, which causes 404 errors for localized URLs.
+
+Polyglot can automatically generate language-prefixed versions of your redirects. Enable this feature in your `_config.yml`:
+
+```yaml
+localize_redirects: true
+exclude_from_redirect_localization:
+  - /signin
+  - /app
+```
+
+With this configuration, a redirect like:
+```
+/github https://github.com/org/repo 302
+```
+
+Will automatically generate localized versions for all your configured languages:
+```
+/github https://github.com/org/repo 302
+/fr/github https://github.com/org/repo 302
+/de/github https://github.com/org/repo 302
+/sv/github https://github.com/org/repo 302
+```
+
+Paths listed in `exclude_from_redirect_localization` will not be localized, which is useful for authentication endpoints or app URLs that should only exist at the root level.
+
 ### Disabling Url Relativizing
 _New in 1.4.0_
 If you dont want a href attribute to be relativized (such as for making [a language switcher](https://github.com/untra/polyglot/blob/main/site/_includes/sidebar.html#L40)), you can use the block tag:
@@ -260,11 +370,50 @@ This plugin stands out from other I18n Jekyll plugins.
 - provides the liquid tag `{{ site.languages }}` to get an array of your I18n strings.
 - provides the liquid tag `{{ site.default_lang }}` to get the default_lang I18n string.
 - provides the liquid tag `{{ site.active_lang }}` to get the I18n language string the website was built for. Alternative names for `active_lang` can be configured via `config.lang_vars`.
+- provides the liquid tag `{{ page.rendered_lang }}` to get the language the page content is actually rendered in (useful for detecting fallback pages).
+- provides the liquid tag `{{ page.available_languages }}` to get the array of language codes a page has been translated into.
+- provides the liquid tag `{{ page.missing_languages }}` to get the array of configured languages a page has not been translated into (empty when the page has no real translations and falls back identically everywhere).
 - provides the liquid tag `{{ I18n_Headers }}` to append SEO bonuses to your website.
 - provides the liquid tag `{{ Unrelativized_Link href="/hello" }}` to make urls that do not get influenced by url correction regexes.
 - provides `site.data` localization for efficient rich text replacement.
 - a creator that will answer all of your questions and issues.
 
+### Detecting Fallback Pages with `page.rendered_lang`
+
+The `page.rendered_lang` variable indicates the actual language of a page's content. This is different from `site.active_lang`, which indicates the language version of the site currently being built.
+
+- `site.active_lang`: The language the site is being built for (e.g., `es` for the Spanish site)
+- `page.rendered_lang`: The language of the page's actual content (e.g., `en` if no Spanish translation exists)
+
+When `page.rendered_lang != site.active_lang`, the page is a **fallback page** - it's being served in the default language because no translation exists.
+
+**Example: Showing a "not translated" notice:**
+```liquid
+{% if page.rendered_lang != site.active_lang %}
+<div class="translation-notice">
+  This page is not yet available in {{ site.active_lang }}.
+  Showing {{ page.rendered_lang }} version.
+</div>
+{% endif %}
+```
+
+**Example: Conditional content based on translation status:**
+```liquid
+{% if page.rendered_lang == site.active_lang %}
+  <!-- This is an actual translation -->
+  <p>Welcome to our {{ site.active_lang }} content!</p>
+{% else %}
+  <!-- This is fallback content -->
+  <p>Content available in {{ page.rendered_lang }} only.</p>
+{% endif %}
+```
+
+This is useful for:
+- Displaying notices when content hasn't been translated
+- Tracking translation coverage
+- Applying different styling to fallback pages
+- Building translation status dashboards
+
 ## SEO Recipes
 Jekyll-polyglot has a few spectacular [Search Engine Optimization techniques](https://untra.github.io/polyglot/seo) to ensure your Jekyll blog gets the most out of its multilingual audience. Check them out!
 
@@ -310,6 +459,10 @@ These are talented and considerate software developers across the world that hav
 * [@obfusk](https://github.com/obfusk) [1.5.0](https://polyglot.untra.io/2021/07/17/polyglot-1.5.0/)
 * [@eighthave](https://github.com/eighthave) [1.5.0](https://polyglot.untra.io/2021/07/17/polyglot-1.5.0/)
 * [@george-gca](https://github.com/george-gca) [pt-BR support](https://polyglot.untra.io/pt-BR/2024/02/29/localized-variables.md)
+* [@PanderMusubi](https://github.com/PanderMusubi) - 1.12 / jekyll-minimal-mistakes-polyglot demo
+* [@GruberMarkus](https://github.com/GruberMarkus) - redirect anchor support
+* [@rathboma](https://github.com/rathboma) - page.rendered_lang / sublanguage redirects
+* [@manabu-nakamura](https://github.com/manabu-nakamura) - Japanese strings
 
 ### Other Websites Built with Polyglot
 Feel free to open a PR and list your multilingual blog here you may want to share:
@@ -328,6 +481,7 @@ Feel free to open a PR and list your multilingual blog here you may want to shar
 * [AnotherTurret just another study note blog](https://aturret.space/)
 * [Diciotech is a collaborative online tech dictionary](https://diciotech.netlify.app/)
 * [Yunseo Kim's Study Notes](https://www.yunseo.kim/)
+* [Beekeeper Studio](https://www.beekeeperstudio.io/)
 
 ## 2.0 Roadmap
 * [x] - **site language**: portuguese Brazil `pt-BR`
@@ -338,6 +492,10 @@ Feel free to open a PR and list your multilingual blog here you may want to shar
 * [x] - **site language**: korean `ko`
 * [x] - **site language**: hebrew `he`
 * [x] - **site language**: chinese China `zh-CN`
+* [x] - **site language**: italian `it`
+* [x] - **site language**: turkish `tk`
+* [x] - **site language**: ukrainian `uk`
+* [x] - **site language**: hindi `hi`
 * [ ] - **site language**: chinese Taiwan `zh-TW`
 * [ ] - **site language**: portuguese Portugal `pt-PT`
 * [ ] - get whitelisted as an official github-pages jekyll plugin

data/lib/jekyll/polyglot/hooks/redirects.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Hook to localize Netlify _redirects file for multilingual sites.
+# When enabled, generates language-prefixed versions of each redirect.
+#
+# Configuration:
+#   localize_redirects: true  # Enable the feature
+#   exclude_from_redirect_localization:  # Optional: paths to skip
+#     - /signin
+#     - /app
+#
+# Example:
+#   Input:  /github https://github.com/org/repo 302
+#   Output: /github https://github.com/org/repo 302
+#           /es/github https://github.com/org/repo 302
+#           /de/github https://github.com/org/repo 302
+#           ...
+
+Jekyll::Hooks.register :polyglot, :post_write do |site|
+  hook_redirects(site)
+end
+
+def hook_redirects(site)
+  return unless site.config.fetch('localize_redirects', false)
+
+  redirects_path = File.join(site.source, '_redirects')
+  return unless File.exist?(redirects_path)
+
+  exclusions = site.config.fetch('exclude_from_redirect_localization', [])
+  lines = File.readlines(redirects_path)
+  localized_lines = []
+
+  lines.each do |line|
+    # Always include the original line
+    localized_lines << line
+
+    # Skip comments and empty lines
+    stripped = line.strip
+    next if stripped.empty? || stripped.start_with?('#')
+
+    # Parse the redirect line: /source /target [status_code]
+    parts = stripped.split(/\s+/)
+    next if parts.length < 2
+
+    source = parts[0]
+
+    # Skip if source is in exclusion list
+    next if exclusions.include?(source)
+
+    # Only process paths that start with /
+    next unless source.start_with?('/')
+
+    # Skip if source already has a language prefix
+    next if site.languages.any? { |lang| source.start_with?("/#{lang}/") || source == "/#{lang}" }
+
+    # Add localized versions for non-default languages
+    site.languages.each do |lang|
+      next if lang == site.default_lang
+
+      localized_source = "/#{lang}#{source}"
+      destination = parts[1]
+
+      # Localize destination if it's an internal path (starts with /)
+      # but not if it's an external URL (contains ://)
+      localized_destination = if destination.start_with?('/') && !destination.include?('://')
+        "/#{lang}#{destination}"
+      else
+        destination
+      end
+
+      rest = parts.length > 2 ? " #{parts[2..].join(' ')}" : ''
+      localized_lines << "#{localized_source} #{localized_destination}#{rest}\n"
+    end
+  end
+
+  # Write to destination
+  dest_path = File.join(site.dest, '_redirects')
+  File.write(dest_path, localized_lines.join)
+end

data/lib/jekyll/polyglot/hooks.rb

@@ -1,2 +1,3 @@
 require_relative 'hooks/coordinate'
 require_relative 'hooks/process'
+require_relative 'hooks/redirects'

data/lib/jekyll/polyglot/liquid/tags/i18n_headers.rb

@@ -12,53 +12,78 @@ module Jekyll
         def render(context)
           site = context.registers[:site]
           page = context.registers[:page]
-          permalink = page['permalink'] || page['url'] || ''
-          permalink = "/#{permalink}" unless permalink.start_with?("/")
-          page_id = page['page_id']
+          permalink = normalize_permalink(page['permalink'] || page['url'] || '')
+          normalized_permalink = strip_lang_prefix(permalink, site.active_lang)
           permalink_lang = page['permalink_lang']
+          site_url = resolve_site_url(site)
+
+          lang_to_permalink = build_lang_to_permalink(site, page['page_id'], normalized_permalink)
+
+          canonical_tag(site, site_url, lang_to_permalink, permalink_lang, normalized_permalink) +
+            hreflang_tags(site, site_url, lang_to_permalink, permalink_lang, normalized_permalink)
+        end
+
+        private
+
+        def normalize_permalink(permalink)
+          permalink.start_with?('/') ? permalink : "/#{permalink}"
+        end
+
+        def strip_lang_prefix(permalink, active_lang)
+          stripped = permalink.delete_prefix("/#{active_lang}/")
+          stripped.start_with?('/') ? stripped : "/#{stripped}"
+        end
+
+        def resolve_site_url(site)
+          return @url unless @url.empty?
+
           baseurl = site.config['baseurl'] || ''
-          site_url = @url.empty? ? site.config['url'] + baseurl : @url
-          i18n = "<meta http-equiv=\"Content-Language\" content=\"#{site.active_lang}\">\n"
+          site.config['url'] + baseurl
+        end
 
-          # Find all documents with the same page_id
-          docs_with_same_id = site.collections.values
-            .flat_map(&:docs)
-            .filter { |doc| !doc.data['page_id'].nil? }
-            .select { |doc| doc.data['page_id'] == page_id }
+        def build_lang_to_permalink(site, page_id, normalized_permalink)
+          site.find_translations(page_id, normalized_permalink)
+        end
 
-          # Build a hash of lang => permalink for all matching docs
-          lang_to_permalink = docs_with_same_id.to_h { |doc| [doc.data['lang'], doc.data['permalink']] }
+        def lookup_permalink(lang_to_permalink, permalink_lang, lang)
+          lang_to_permalink[lang] || (permalink_lang && permalink_lang[lang])
+        end
 
-          # Canonical should always point to the current page's permalink (active_lang)
+        def with_lang_prefix(permalink, lang)
+          permalink.start_with?("/#{lang}/") ? permalink : "/#{lang}#{permalink}"
+        end
+
+        def canonical_tag(site, site_url, lang_to_permalink, permalink_lang, normalized_permalink)
           current_lang = site.active_lang
-          current_permalink = lang_to_permalink[current_lang] || (permalink_lang && permalink_lang[current_lang]) || permalink
-          current_permalink = "/#{current_permalink}" unless current_permalink.start_with?("/")
-          # Don't add language prefix if it's already in the permalink
-          canonical_permalink = if current_lang == site.default_lang
-            current_permalink
+          has_translation = lookup_permalink(lang_to_permalink, permalink_lang, current_lang)
+          use_default = site.fallback_canonical_to_default_lang && !has_translation && current_lang != site.default_lang
+
+          canonical = if use_default
+            normalize_permalink(lookup_permalink(lang_to_permalink, permalink_lang, site.default_lang) || normalized_permalink)
+          elsif current_lang == site.default_lang
+            normalize_permalink(lookup_permalink(lang_to_permalink, permalink_lang, current_lang) || normalized_permalink)
           else
-            current_permalink.start_with?("/#{current_lang}/") ? current_permalink : "/#{current_lang}#{current_permalink}"
+            current = normalize_permalink(lookup_permalink(lang_to_permalink, permalink_lang, current_lang) || normalized_permalink)
+            with_lang_prefix(current, current_lang)
           end
-          i18n += "<link rel=\"canonical\" href=\"#{site_url}#{canonical_permalink}\"/>\n"
-
-          # Get the default language permalink for x-default
-          default_lang_permalink = lang_to_permalink[site.default_lang] || (permalink_lang && permalink_lang[site.default_lang]) || permalink
-          default_lang_permalink = "/#{default_lang_permalink}" unless default_lang_permalink.start_with?("/")
-
-          site.languages.each do |lang|
-            alt_permalink = lang_to_permalink[lang] || (permalink_lang && permalink_lang[lang]) || permalink
-            alt_permalink = "/#{alt_permalink}" unless alt_permalink.start_with?("/")
-            i18n += if lang == site.default_lang
-              "<link rel=\"alternate\" hreflang=\"#{lang}\" href=\"#{site_url}#{alt_permalink}\"/>\n" \
-                "<link rel=\"alternate\" hreflang=\"x-default\" href=\"#{site_url}#{default_lang_permalink}\"/>\n"
+          "<link rel=\"canonical\" href=\"#{site_url}#{canonical}\"/>\n"
+        end
+
+        def hreflang_tags(site, site_url, lang_to_permalink, permalink_lang, normalized_permalink)
+          default_permalink = normalize_permalink(lookup_permalink(lang_to_permalink, permalink_lang, site.default_lang) || normalized_permalink)
+
+          site.languages.map do |lang|
+            has_translation = lookup_permalink(lang_to_permalink, permalink_lang, lang)
+            next nil if !has_translation && lang != site.default_lang
+
+            alt = normalize_permalink(lookup_permalink(lang_to_permalink, permalink_lang, lang) || normalized_permalink)
+            if lang == site.default_lang
+              "<link rel=\"alternate\" hreflang=\"#{lang}\" href=\"#{site_url}#{alt}\"/>\n" \
+                "<link rel=\"alternate\" hreflang=\"x-default\" href=\"#{site_url}#{default_permalink}\"/>\n"
             else
-              # For non-default languages, use the language-specific permalink directly
-              # Don't add the language prefix if it's already in the permalink
-              lang_permalink = alt_permalink.start_with?("/#{lang}/") ? alt_permalink : "/#{lang}#{alt_permalink}"
-              "<link rel=\"alternate\" hreflang=\"#{lang}\" href=\"#{site_url}#{lang_permalink}\"/>\n"
+              "<link rel=\"alternate\" hreflang=\"#{lang}\" href=\"#{site_url}#{with_lang_prefix(alt, lang)}\"/>\n"
             end
-          end
-          i18n
+          end.compact.join
         end
       end
     end

data/lib/jekyll/polyglot/patches/jekyll/site.rb

@@ -1,10 +1,9 @@
-require 'English'
 require 'etc'
 
 include Process
 module Jekyll
   class Site
-    attr_reader :default_lang, :languages, :exclude_from_localization, :lang_vars, :lang_from_path
+    attr_reader :default_lang, :languages, :exclude_from_localization, :lang_vars, :lang_from_path, :fallback_canonical_to_default_lang
     attr_accessor :file_langs, :active_lang
 
     def prepare
@@ -12,6 +11,7 @@ module Jekyll
       fetch_languages
       @parallel_localization = config.fetch('parallel_localization', true)
       @lang_from_path = config.fetch('lang_from_path', false)
+      @fallback_canonical_to_default_lang = config.fetch('fallback_canonical_to_default_lang', false)
       @exclude_from_localization = config.fetch('exclude_from_localization', []).map do |e|
         if File.directory?(e) && e[-1] != '/'
           "#{e}/"
@@ -47,7 +47,7 @@ module Jekyll
                 next unless waitpid pid, Process::WNOHANG
 
                 pids.delete pid_lang
-                raise "Polyglot subprocess #{pid} (#{lang}) failed (#{$CHILD_STATUS.exitstatus})" unless $CHILD_STATUS.success?
+                raise "Polyglot subprocess #{pid} (#{pid_lang}) failed (#{$?.exitstatus})" unless $?.success?
               end
             end
           end
@@ -131,11 +131,9 @@ module Jekyll
       end
 
       segments = split_on_multiple_delimiters(doc.path)
-      # loop through all segments and check if they match the language regex
       segments.each do |segment|
-        if @languages.include?(segment)
-          return segment
-        end
+        match = @languages.find { |lang| lang.downcase == segment.downcase }
+        return match if match
       end
 
       nil
@@ -148,12 +146,38 @@ module Jekyll
     def coordinate_documents(docs)
       regex = document_url_regex
       approved = {}
+      # Build set of valid languages (default + configured)
+      valid_languages = ([@default_lang] + @languages).uniq
+
       docs.each do |doc|
-        lang = doc.data['lang'] || derive_lang_from_path(doc) || @default_lang
+        # Get the explicitly declared language (frontmatter or path-derived)
+        explicit_lang = doc.data['lang'] || derive_lang_from_path(doc)
+        lang = explicit_lang || @default_lang
+
+        # FILTER: Skip documents whose explicit lang is not in configured languages.
+        # Check the explicit value (not the fallback) so that documents with an
+        # unconfigured lang like 'de' are excluded even if normalization would
+        # map them to default_lang. Compare case-insensitively so case-mismatched
+        # frontmatter (e.g. 'pt-br' vs configured 'pt-BR') is normalized below
+        # rather than rejected here.
+        if explicit_lang && valid_languages.none? { |l| l.downcase == explicit_lang.downcase }
+          Jekyll.logger.warn "Polyglot:", "Skipping #{doc.relative_path} - lang '#{explicit_lang}' not in configured languages #{valid_languages.inspect}"
+          next
+        end
+
+        # If the doc lang matches a config language case-insensitively, use the config case
+        config_lang = @languages.find { |l| l.downcase == lang.downcase }
+        lang = config_lang if config_lang
+        doc.data['lang'] = lang if doc.data['lang'] && config_lang
+
         lang_exclusive = doc.data['lang-exclusive'] || []
+
         url = doc.url.gsub(regex, '/')
         page_id = doc.data['page_id'] || url
         doc.data['permalink'] = url if doc.data['permalink'].to_s.empty? && !doc.data['lang'].to_s.empty?
+        # Set rendered_lang to indicate what language this page is actually rendered in
+        # This allows templates to detect fallback pages (rendered_lang != active_lang)
+        doc.data['rendered_lang'] = lang
 
         # skip entirely if nothing to check
         next if @file_langs.nil?
@@ -175,38 +199,102 @@ module Jekyll
     end
 
     def assignPageRedirects(doc, docs)
+      # Preserve and normalize user-defined redirect_from
+      user_redirects = doc.data['redirect_from'] || []
+      user_redirects = [user_redirects] unless user_redirects.is_a?(Array)
+
+      # Determine document language
+      doc_lang = doc.data['lang'] || derive_lang_from_path(doc) || @default_lang
+
+      # Scope user-defined redirects to document's language if non-default
+      if doc_lang != @default_lang && !user_redirects.empty?
+        user_redirects = user_redirects.map do |redirect_path|
+          # Normalize path to start with /
+          redirect_path = "/#{redirect_path}" unless redirect_path.start_with?('/')
+          # Only prefix if not already prefixed with this language
+          if redirect_path.start_with?("/#{doc_lang}/")
+            redirect_path
+          else
+            "/#{doc_lang}#{redirect_path}"
+          end
+        end
+      end
+
+      # Compute page_id based redirects (cross-language)
+      computed_redirects = []
       pageId = doc.data['page_id']
       if !pageId.nil? && !pageId.empty?
-        redirects = []
-
         docs_with_same_id = docs.select { |dd| dd.data['page_id'] == pageId }
-
-        # For each document with the same page_id
         docs_with_same_id.each do |dd|
-          # Add redirect if it's a different permalink
           if dd.data['permalink'] != doc.data['permalink']
-            redirects << dd.data['permalink']
+            computed_redirects << dd.data['permalink']
           end
         end
-
-        doc.data['redirect_from'] = redirects
       end
+
+      # Merge user-defined and computed redirects, removing duplicates
+      all_redirects = (user_redirects + computed_redirects).uniq
+      doc.data['redirect_from'] = all_redirects unless all_redirects.empty?
     end
 
     def assignPageLanguagePermalinks(doc, docs)
-      pageId = doc.data['page_id']
-      if !pageId.nil? && !pageId.empty?
-        unless doc.data['permalink_lang'] then doc.data['permalink_lang'] = {} end
-        permalinkDocs = docs.select do |dd|
-          dd.data['page_id'] == pageId
-        end
-        permalinkDocs.each do |dd|
-          doclang = dd.data['lang'] || derive_lang_from_path(dd) || @default_lang
-          doc.data['permalink_lang'][doclang] = dd.data['permalink']
+      page_id = doc.data['page_id']
+      normalized_permalink = normalized_permalink_for_doc(doc)
+      translations = find_translations(page_id, normalized_permalink, docs)
+
+      doc.data['permalink_lang'] = translations
+      configured = ([@default_lang] + @languages).uniq
+      doc.data['available_languages'] = translations.keys
+      # missing_languages signals "a visitor in this lang would see different
+      # content than another lang's visitor". A single-source page falls back
+      # identically everywhere, so nothing is missing in that case.
+      doc.data['missing_languages'] =
+        translations.size > 1 ? (configured - translations.keys) : []
+    end
+
+    # Returns a hash of { lang => permalink } for all docs that are translations
+    # of the given page. Matches by page_id when present, otherwise by normalized
+    # permalink. Filters out languages not in the configured languages list.
+    # candidate_docs defaults to site.collections + site.pages so the helper can
+    # be called from Liquid render contexts where the caller doesn't already
+    # hold a docs array.
+    def find_translations(page_id, normalized_permalink, candidate_docs = nil)
+      candidate_docs ||= collections.values.flat_map(&:docs) + pages
+      valid_languages = ([@default_lang] + @languages).uniq
+
+      matching =
+        if !page_id.to_s.empty?
+          candidate_docs.select { |d| d.data['page_id'] == page_id }
+        elsif !normalized_permalink.to_s.empty?
+          candidate_docs.select { |d| normalized_permalink_for_doc(d) == normalized_permalink }
+        else
+          []
         end
+
+      matching.each_with_object({}) do |d, h|
+        explicit_lang = d.data['lang'] || derive_lang_from_path(d)
+        doclang = explicit_lang || @default_lang
+        next if explicit_lang && !valid_languages.include?(explicit_lang)
+
+        h[doclang] = d.data['permalink']
       end
     end
 
+    # Returns the doc's permalink with its own language prefix stripped, so it
+    # can be matched against sibling docs that share the same un-prefixed
+    # permalink. Returns nil when no usable permalink is present.
+    def normalized_permalink_for_doc(doc)
+      permalink = doc.data['permalink'] || (doc.respond_to?(:url) ? doc.url : nil)
+      return nil if permalink.to_s.empty?
+
+      permalink = "/#{permalink}" unless permalink.start_with?('/')
+      lang = doc.data['lang']
+      return permalink if lang.to_s.empty?
+
+      stripped = permalink.delete_prefix("/#{lang}/")
+      stripped.start_with?('/') ? stripped : "/#{stripped}"
+    end
+
     # performs any necessary operations on the documents before rendering them
     def process_documents(docs)
       # return if @active_lang == @default_lang
@@ -275,7 +363,9 @@ module Jekyll
         end
       end
       start = disabled ? 'ferh' : 'href'
-      neglookbehind = disabled ? "" : "(?<!hreflang=\"#{@default_lang}\" |rel=\"canonical\" )"
+      # Build negative lookbehind to exclude hreflang URLs from relativization
+      # hreflang tags for default language and x-default should not be relativized
+      neglookbehind = disabled ? "" : "(?<!hreflang=\"#{@default_lang}\" |hreflang=\"x-default\" )"
       %r{#{neglookbehind}#{start}="?#{url}#{@baseurl}/((?:#{regex}[^,'"\s/?.]+\.?)*(?:/[^\]\[)("'\s]*)?)"}
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-polyglot
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.13.0
 platform: ruby
 authors:
 - Samuel Volin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-20 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -44,6 +44,7 @@ files:
 - lib/jekyll/polyglot/hooks/assets-toggle.rb
 - lib/jekyll/polyglot/hooks/coordinate.rb
 - lib/jekyll/polyglot/hooks/process.rb
+- lib/jekyll/polyglot/hooks/redirects.rb
 - lib/jekyll/polyglot/liquid.rb
 - lib/jekyll/polyglot/liquid/tags/i18n_headers.rb
 - lib/jekyll/polyglot/liquid/tags/static_href.rb
@@ -71,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 3.1.0
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: I18n plugin for Jekyll Blogs