jekyll-l10n 1.2.8 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5a4a4261253d5efb8103b3d8896bff9960249f4d6ed69266c0016729b38da43
-  data.tar.gz: 582bb044c024621b3bee6407f0ef6f2c6d3f3de8cbca9df14c2449702aaeb446
+  metadata.gz: 7fa24f781e7892870dbdd97d38606b511024be5d0bf026ff4f9fca0b4d680738
+  data.tar.gz: 298e9757f9dd189fdc41d5c545e019c4f2a82a607512944efa31ac61df639100
 SHA512:
-  metadata.gz: cb0212b0e62d331499629fe94eb3983dbaba9d4414804be1f1846873619935acbecf8f26d405b5c10cdc4400bdd246c23f35697ab67bc58deae24b506280f516
-  data.tar.gz: dde77b84bb811f0e08fb3bf4cf613cc8cef18bb39e907c7b0bf53a6c0993e33c399bf8b089cab60cbbe5e597725616aae1575b2c21fc9372c299759430c393ba
+  metadata.gz: 6153450cfcf936014afac2e2c96aa7d6be1b6995de8c03c7551a329bdad32ae7f4b353bd82068e14aa64b6612bfdfa0f69a53bfabcf850a5401e43f097bf02c8
+  data.tar.gz: a366a109b99e560a8ec305a1a0db3807dbdc903d2a45007f47382d2a5f7a19a13ce8de7b7eb2010a933bcd9ac72b2016e49e65c890c7b98e29eea6602e9c420c

data/README.md

@@ -1,85 +1,65 @@
 # jekyll-l10n
 
-`jekyll-l10n` is a Jekyll plugin that streamlines the localization of static
-websites using industry-standard GNU Gettext PO files. Creating multilingual
-sites presents unique challenges: maintaining consistent translations across
-multiple pages, managing translation workflows with non-technical translators,
-and keeping translations synchronized as content evolves. This plugin automates
-these challenges by integrating the proven Gettext workflow directly into your
-Jekyll build pipeline.
-
-The plugin works by extracting translatable strings from your site's generated
-HTML and organizing them into PO files that translators can edit using standard
-translation tools. As your content changes, the plugin intelligently updates
-these translation files, preserving existing translations while flagging
-changed or new content. When you rebuild your site, translated strings are
-automatically applied to localized versions of your pages, producing fully
-translated HTML output with locale-prefixed URLs.
+`jekyll-l10n` is a Jekyll plugin that streamlines the localization of static websites using industry-standard GNU Gettext PO files. It extracts translatable strings from your site's HTML, organizes them into PO files for professional translation, and automatically applies translations to generate fully localized pages with locale-prefixed URLs.
 
 ![Jekyll site localization](docs/assets/img/jekyll-l10n.png)
 
-Key features include automatic page duplication with locale-specific URL
-prefixes, flexible fallback modes when translations are incomplete (display
-original English, mark untranslated strings, or leave blank), and support for
-compendium files to share common translations across your site. By leveraging
-the standard Gettext format and workflow, `jekyll-l10n` enables collaboration
-with professional translators and integrates with existing translation
-management systems, while keeping your source content in Markdown where it
-belongs.
+## Installation
 
-## Development Setup
+Add to your Jekyll site's `Gemfile`:
 
-To set up your development environment:
-
-```bash
-bundle install          # Install Ruby dependencies
-pip install pre-commit  # Install pre-commit framework
-pre-commit install      # Install pre-commit hooks
+```ruby
+gem "jekyll-l10n", "~> 1.1"
 ```
 
-This enables pre-commit hooks that automatically check code style and format on each commit.
+Run `bundle install`, then enable in `_config.yml`:
 
-## Configuration
+```yaml
+plugins:
+  - jekyll-l10n
+
+defaults:
+  - scope:
+      type: "pages"
+    values:
+      with_locales: true
+      with_locales_data:
+        locales: ["es", "fr", "de"]
+        locales_dir: "_locales"
+        extract_on_build: true
+```
 
-### Incremental Builds (Performance Optimization)
+## Quick Example
 
-By default, the plugin regenerates all localized pages on every build. For large
-sites with many locales, this can impact build performance. You can enable
-incremental build support to skip regenerating pages that haven't changed:
+Edit PO files in `_locales/` with translations. On rebuild, your site will generate:
 
-```yaml
-localization_gettext:
-  with_locales_data:
-    incremental: true # Enable incremental builds
-```
+- `/es/` - Spanish pages
+- `/fr/` - French pages
+- `/de/` - German pages
 
-Or at the top level:
+## Documentation
 
-```yaml
-localization_gettext:
-  incremental: true
-```
+Complete documentation is available in the [docs/](docs/) directory:
 
-When incremental mode is enabled, pages are only regenerated if:
+- **[Getting Started](docs/getting-started/)** - Installation requirements and first-site setup
+- **[Configuration Guide](docs/configuration/)** - All configuration options and settings
+- **[Guides](docs/guides/)** - Fallback modes, Liquid filters, machine translation, incremental builds
+- **[Development](docs/development/)** - Setup, testing, API documentation
+- **[Examples](docs/examples/)** - Real-world usage examples
 
-- The source page content has been modified
-- Any PO translation files have been updated
-- The Jekyll configuration has changed
+## Key Features
 
-This significantly improves build times on subsequent builds when only
-translations or a few pages have changed.
+- **Automatic extraction** - Extract translatable strings during Jekyll builds
+- **Professional workflows** - Edit translations using standard Gettext tools (Poedit, Weblate, etc.)
+- **Fallback modes** - Display English, mark untranslated strings, or leave blank
+- **Incremental builds** - Skip regenerating unchanged localized pages for faster builds
+- **Machine translation** - Optional LibreTranslate integration for initial translations
+- **Compendium files** - Share common translations across your entire site
 
-## Machine Translation
+## Requirements
 
-For teams without translation resources, the plugin integrates with
-LibreTranslate, a free and open-source machine translation service, to
-automatically translate newly extracted strings during the extraction workflow.
-You can enable this optional integration on a per-locale basis, allowing
-LibreTranslate to generate initial translations for compendia files that serve
-as a foundation for professional translators to refine. This significantly
-reduces the initial translation effort and helps bootstrap localization for new
-content, though professional review is still recommended for
-publication-quality results.
+- **Ruby**: >= 2.7.0
+- **Jekyll**: >= 4.0, < 5.0
 
 ## License
 
@@ -88,7 +68,7 @@ MIT License - see LICENSE file for details.
 ## Contributing
 
 1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'feat: Add amazing feature'`)
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request

data/lib/jekyll-l10n/constants.rb

@@ -30,7 +30,7 @@ module Jekyll
       # @return [String] "english"
       FALLBACK_MODE_ENGLISH = "english"
 
-      # Fallback mode: wrap untranslated text with markers (e.g., "[UNTRANSLATED: text]")
+      # Fallback mode: wrap untranslated text with markers (e.g., "[UNTRANSLATED] text")
       # @return [String] "marker"
       FALLBACK_MODE_MARKER = "marker"
 
@@ -94,6 +94,11 @@ module Jekyll
 
       # ## LibreTranslate Integration Defaults
 
+      # Default LibreTranslate API endpoint URL
+      # Uses localhost:5000 as default for local development
+      # @return [String] "http://localhost:5000"
+      DEFAULT_LIBRETRANSLATE_API_URL = "http://localhost:5000"
+
       # Default timeout (in seconds) for LibreTranslate API requests
       # @return [Integer] 300 seconds (5 minutes)
       DEFAULT_LIBRETRANSLATE_TIMEOUT = 300

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

@@ -42,10 +42,14 @@ module Jekyll
       # It iterates through all pages in the site, identifies those marked for localization,
       # and creates locale-specific variants.
       #
+      # Returns early with no output if no pages are marked for localization.
+      #
       # @param site [Jekyll::Site] The Jekyll site object containing pages to process
       # @return [void]
       # @see LocalizedPage for details on page structure
       def generate(site)
+        return unless any_pages_to_localize?(site)
+
         Jekyll.logger.info "Localization", "Generating localized pages..."
         generate_localized_pages(site)
       end
@@ -117,6 +121,14 @@ module Jekyll
 
         locale.match?(%r!^[a-z]{2}(_[A-Z]{2})?$!)
       end
+
+      # Check if any pages in the site are marked for localization
+      #
+      # @param site [Jekyll::Site] The Jekyll site object
+      # @return [Boolean] True if at least one page has with_locales set to true
+      def any_pages_to_localize?(site)
+        site.pages.any? { |page| page.data["with_locales"] == true }
+      end
     end
   end
 end

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

@@ -54,9 +54,13 @@ module Jekyll
       # 2. Updates PO files with new entries and modified translations
       # 3. If PO files were created or updated, reprocess localized pages to apply translations
       #
+      # Returns early with no output if no pages are marked for localization.
+      #
       # @return [void]
       # @note This is automatically called by Jekyll's site:post_write hook
       def process_localizations
+        return unless any_pages_localized?
+
         extractor = Extractor.new(@site)
         extraction_result = extractor.extract_site
 
@@ -66,6 +70,15 @@ module Jekyll
           reprocessor.reprocess_localized_pages
         end
       end
+
+      private
+
+      # Check if any pages in the site are marked for localization
+      #
+      # @return [Boolean] True if at least one page has with_locales set to true
+      def any_pages_localized?
+        @site.pages.any? { |page| page.data["with_locales"] == true }
+      end
     end
   end
 end

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

@@ -160,9 +160,9 @@ module Jekyll
       #    Example: "Hello World" -> "Hello World" (if no translation found)
       #
       # 2. :marker
-      #    Wraps text with visible marker "[UNTRANSLATED: ...]"
+      #    Wraps text with visible marker "[UNTRANSLATED] ..."
       #    Best for: QA/Development - clearly identifies missing translations
-      #    Example: "Hello World" -> "[UNTRANSLATED: Hello World]"
+      #    Example: "Hello World" -> "[UNTRANSLATED] Hello World"
       #    Why: Stakeholders can see exactly which content needs translation
       #
       # 3. :empty

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

@@ -215,9 +215,9 @@ module Jekyll
       #
       # Example: "https://api.libretranslate.de" or "http://localhost:5000"
       #
-      # @return [String, nil] The API URL, or nil if not configured
+      # @return [String] The API URL (default: "http://localhost:5000")
       def libretranslate_api_url
-        libretranslate_config["libretranslate_api_url"]
+        libretranslate_config["libretranslate_api_url"] || Constants::DEFAULT_LIBRETRANSLATE_API_URL
       end
 
       # Get the LibreTranslate API key (if required)
@@ -267,10 +267,11 @@ module Jekyll
       # If true, any API error will halt the translation process. If false, errors are logged
       # but translation continues with other entries.
       #
-      # @return [Boolean] true if errors should stop translation (default), false if
-      #   translation continues
+      # @return [Boolean] true if errors should stop translation, false if
+      #   translation continues (default: false)
       def libretranslate_stop_on_error?
-        libretranslate_config["libretranslate_stop_on_error"] != false
+        val = libretranslate_config["libretranslate_stop_on_error"]
+        val.nil? ? Constants::DEFAULT_LIBRETRANSLATE_STOP_ON_ERROR : val != false
       end
 
       # Get the interval for logging LibreTranslate translation progress

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-l10n
 version: !ruby/object:Gem::Version
-  version: 1.2.8
+  version: 1.3.0
 platform: ruby
 authors:
 - ReleaseBot
@@ -55,7 +55,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '1.12'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
@@ -65,7 +65,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '1.12'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'