accept_language 2.0.6 → 2.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23f2f41d72b0b3ba8c16bfb544a85ac5d35fc509f1f057fee5d64c7756215dff
-  data.tar.gz: a32c6e726b1bb521c7478b11bde767e7c8990320892efa928e39814c97334931
+  metadata.gz: 0afa534a141f111edb4f47449bccb2b44795abd11512319bee75909f672133ab
+  data.tar.gz: e90f24a3a8104eb8fff13ee15ce7660705e31565769c95e62d4fb4577ff1c816
 SHA512:
-  metadata.gz: 6b161891fe7c1014dbe547e4ad932466f0e22741990ca6fbe43f9a559b20e789fd3323ea78211a2c7feb5e5eda8efca6e30c902edc4505d66ccdc89b9158fd11
-  data.tar.gz: 2c25818bea47bfc094315b06a116d96583c3aeb3fb36e5bd309b3d74bbea679c0153e5a99dabe4af33785d2b9004644f7c680fa831e4bae7eea9e18a79baee22
+  metadata.gz: 6d098319c113b5ed61b7b57a57ce78cde8b799d9256240dc076de8626d5021ad4840f96b23b94bcba1d64dc7930e66514da17d4d55d8107c417a9c102a99925b
+  data.tar.gz: c4695ea31539c0c94713b569e424fd2901a85a4ac67a448ef1c9cd200333fdaa1ab4bfe7429d1b7155fb2c4f4d2ffcf4218d2fee2060f9ffb6b629accc50a56e

data/README.md

@@ -48,40 +48,99 @@ gem install accept_language
 
 ## Usage
 
-`Accept Language` library is primarily designed to assist web servers in serving multilingual content based on user preferences expressed in the `Accept-Language` header. This library finds the best matching language from the available languages your application supports and the languages the user prefers.
+The `Accept Language` library helps web applications serve content in the user's preferred language by parsing the `Accept-Language` HTTP header. This header indicates the user's language preferences and their priority order.
 
-Below are some examples of how you might use the library:
+### Basic Syntax
+
+The library has two main methods:
+
+- `AcceptLanguage.parse(header)`: Parses the Accept-Language header
+- `match(*available_languages)`: Matches against the languages your application supports
+
+```ruby
+AcceptLanguage.parse("fr-CH, fr;q=0.9").match(:fr, :"fr-CH") # => :"fr-CH"
+```
+
+### Understanding Language Preferences
+
+#### Simple Language Matching
 
 ```ruby
-# The user prefers Danish, then British English, and finally any kind of English.
-# Since your application supports English and Danish, it selects Danish as it's the user's first choice.
+# Header: "da" (Danish is the preferred language)
+# Available: :en and :da
+AcceptLanguage.parse("da").match(:en, :da) # => :da
+
+# No match available - returns nil
+AcceptLanguage.parse("da").match(:fr, :en) # => nil
+```
+
+#### Quality Values (q-values)
+
+Q-values range from 0 to 1 and indicate preference order:
+
+```ruby
+# Header: "da, en-GB;q=0.8, en;q=0.7"
+# Means:
+#   - Danish (da): q=1.0 (highest priority)
+#   - British English (en-GB): q=0.8 (second choice)
+#   - Generic English (en): q=0.7 (third choice)
 AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :da) # => :da
+AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :"en-GB") # => :"en-GB"
+```
 
-# The user prefers Danish, then English, and finally Uyghur. Your application supports British English and Chinese Uyghur.
-# Here, the library will return Chinese Uyghur because it's the highest ranked language in the user's list that your application supports.
-AcceptLanguage.parse("da, en;q=0.8, ug;q=0.9").match("en-GB", "ug-CN") # => "ug-CN"
+#### Language Variants
 
-# The user prefers Danish, then British English, and finally any kind of English. Your application only supports Japanese.
-# Since none of the user's preferred languages are supported, it returns nil.
-AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:ja) # => nil
+The library handles specific language variants (regional or script variations):
 
-# The user only accepts Swiss French, but your application only supports French. Since Swiss French and French are not the same, it returns nil.
-AcceptLanguage.parse("fr-CH").match(:fr) # => nil
+```ruby
+# Specific variants must match exactly
+AcceptLanguage.parse("fr-CH").match(:fr) # => nil (Swiss French ≠ Generic French)
+
+# But generic variants can match specific ones
+AcceptLanguage.parse("fr").match(:"fr-CH") # => :"fr-CH"
+
+# Script variants are also supported
+AcceptLanguage.parse("uz-Latn-UZ").match("uz-Latn-UZ") # => "uz-Latn-UZ"
+```
+
+#### Wildcards and Exclusions
+
+The `*` wildcard matches any language, and `q=0` excludes languages:
+
+```ruby
+# Accept any language but prefer German
+AcceptLanguage.parse("de-DE, *;q=0.5").match(:fr) # => :fr (matched by wildcard)
 
-# The user prefers German, then any language except French. Your application supports French.
-# Even though the user specified a wildcard, they explicitly excluded French. Therefore, it returns nil.
-AcceptLanguage.parse("de, zh;q=0.4, *;q=0.5, fr;q=0").match(:fr) # => nil
+# Accept any language EXCEPT English
+AcceptLanguage.parse("*, en;q=0").match(:en) # => nil (explicitly excluded)
+AcceptLanguage.parse("*, en;q=0").match(:fr) # => :fr (matched by wildcard)
+```
 
-# The user prefers Uyghur (in Latin script, as used in Uzbekistan). Your application supports this exact variant of Uyghur.
-# Since the user's first choice matches a language your application supports, it returns that language.
-AcceptLanguage.parse("uz-latn-uz").match("uz-Latn-UZ") # => "uz-Latn-UZ"
+#### Complex Example
 
-# The user doesn't mind what language they get, but they'd prefer not to have English. Your application supports English.
-# Even though the user specified a wildcard, they explicitly excluded English. Therefore, it returns nil.
-AcceptLanguage.parse("*, en;q=0").match("en") # => nil
+```ruby
+# Header: "de-LU, fr;q=0.9, en;q=0.7, *;q=0.5"
+# Means:
+#   - Luxembourg German: q=1.0 (highest priority)
+#   - French: q=0.9 (second choice)
+#   - English: q=0.7 (third choice)
+#   - Any other language: q=0.5 (lowest priority)
+header = "de-LU, fr;q=0.9, en;q=0.7, *;q=0.5"
+parser = AcceptLanguage.parse(header)
+
+parser.match(:de, :"de-LU") # => :"de-LU" (exact match)
+parser.match(:fr, :en)      # => :fr (higher q-value)
+parser.match(:es, :it)      # => :es (matched by wildcard)
 ```
 
-These examples show the flexibility and power of `Accept Language`. By giving your application a deep understanding of the user's language preferences, `Accept Language` can significantly improve user satisfaction and engagement with your application.
+### Case Sensitivity
+
+The matching is case-insensitive but preserves the case of the returned value:
+
+```ruby
+AcceptLanguage.parse("en-GB").match("en-gb") # => "en-gb"
+AcceptLanguage.parse("en-gb").match("en-GB") # => "en-GB"
+```
 
 ### Rails integration example
 
@@ -95,6 +154,7 @@ class ApplicationController < ActionController::Base
   end
 
   def best_locale_from_request
+    # HTTP_ACCEPT_LANGUAGE is the standardized key for the Accept-Language header in Rack/Rails
     return I18n.default_locale unless request.headers.key?("HTTP_ACCEPT_LANGUAGE")
 
     string = request.headers.fetch("HTTP_ACCEPT_LANGUAGE")

data/lib/accept_language/matcher.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module AcceptLanguage
-  # A utility class that provides functionality to match the Accept-Language header value
-  # against the languages supported by your application. This helps in identifying the most
-  # suitable languages to present to the user based on their preferences.
+  # Matches Accept-Language header values against application-supported languages to determine
+  # the optimal language choice. Handles quality values, wildcards, and language tag matching
+  # according to RFC 2616 specifications.
   #
   # @example
   #   Matcher.new("da" => 1.0, "en-GB" => 0.8, "en" => 0.7).call(:ug, :kk, :ru, :en) # => :en
@@ -34,41 +34,51 @@ module AcceptLanguage
       @preferred_langtags = langtags.compact.reverse
     end
 
-    # Matches the user's preferred languages against the available languages of your application.
-    # It prioritizes higher quality values and returns the most suitable match.
+    # Finds the optimal language match by comparing user preferences against available languages.
+    # Handles priorities based on:
+    # 1. Explicit quality values (q-values)
+    # 2. Language tag specificity (exact matches preferred over partial matches)
+    # 3. Order of preference in the original Accept-Language header
     #
-    # @param [Array<String, Symbol>] available_langtags An array representing the languages available in your application.
-    #
-    # @example When Uyghur, Kazakh, Russian and English languages are available.
-    #   call(:ug, :kk, :ru, :en)
-    #
-    # @return [String, Symbol, nil] The language that best matches the user's preferences, or nil if there is no match.
+    # @param [Array<String, Symbol>] available_langtags Languages supported by your application
+    # @return [String, Symbol, nil] Best matching language or nil if no acceptable match found
+    # @raise [ArgumentError] If any language tag is nil
     def call(*available_langtags)
-      available_langtags = drop_unacceptable(*available_langtags)
+      raise ::ArgumentError, "Language tags cannot be nil" if available_langtags.any?(&:nil?)
+
+      filtered_tags = drop_unacceptable(*available_langtags)
+      return nil if filtered_tags.empty?
+
+      find_best_match(filtered_tags)
+    end
 
+    private
+
+    def find_best_match(available_langtags)
       preferred_langtags.each do |preferred_tag|
-        if wildcard?(preferred_tag)
-          langtag = any_other_langtag(*available_langtags)
-          return langtag unless langtag.nil?
-        else
-          available_langtags.each do |available_langtag|
-            return available_langtag if available_langtag.match?(/\A#{preferred_tag}/i)
-          end
-        end
+        match = match_langtag(preferred_tag, available_langtags)
+        return match if match
       end
 
       nil
     end
 
-    private
+    def match_langtag(preferred_tag, available_langtags)
+      if wildcard?(preferred_tag)
+        any_other_langtag(*available_langtags)
+      else
+        find_matching_tag(preferred_tag, available_langtags)
+      end
+    end
+
+    def find_matching_tag(preferred_tag, available_langtags)
+      available_langtags.find { |tag| tag.match?(/\A#{preferred_tag}/i) }
+    end
 
     def any_other_langtag(*available_langtags)
       available_langtags.find do |available_langtag|
         langtags = preferred_langtags - [WILDCARD]
-
-        langtags.none? do |langtag|
-          available_langtag.match?(/\A#{langtag}/i)
-        end
+        langtags.none? { |tag| available_langtag.match?(/\A#{tag}/i) }
       end
     end
 
@@ -81,9 +91,7 @@ module AcceptLanguage
     end
 
     def unacceptable?(langtag)
-      excluded_langtags.any? do |excluded_langtag|
-        langtag.match?(/\A#{excluded_langtag}/i)
-      end
+      excluded_langtags.any? { |excluded_tag| langtag.match?(/\A#{excluded_tag}/i) }
     end
 
     def wildcard?(value)

data/lib/accept_language/parser.rb

@@ -3,8 +3,9 @@
 require "bigdecimal"
 
 module AcceptLanguage
-  # Parser is a utility class responsible for parsing Accept-Language header fields.
-  # It processes the field to extract language tags and their respective quality values.
+  # Parses Accept-Language header fields into structured data, extracting language tags
+  # and their quality values (q-values). Validates input according to RFC 2616 specifications
+  # and handles edge cases like malformed inputs and implicit quality values.
   #
   # @example
   #   Parser.new("da, en-GB;q=0.8, en;q=0.7")
@@ -12,11 +13,17 @@ module AcceptLanguage
   #
   # @see https://tools.ietf.org/html/rfc2616#section-14.4 for more information on Accept-Language header fields.
   class Parser
-    DEFAULT_QUALITY = BigDecimal("1")
+    DEFAULT_QUALITY = "1"
     SEPARATOR = ","
     SPACE = " "
     SUFFIX = ";q="
 
+    # Validates q-values according to RFC 2616:
+    # - Must be between 0 and 1
+    # - Can have up to 3 decimal places
+    # - Allows both forms: .8 and 0.8
+    QVALUE_PATTERN = /\A(?:0(?:\.[0-9]{1,3})?|1(?:\.0{1,3})?|\.[0-9]{1,3})\z/
+
     attr_reader :languages_range
 
     # Initializes a new Parser instance by importing and processing the given Accept-Language header field.
@@ -26,14 +33,15 @@ module AcceptLanguage
       @languages_range = import(field)
     end
 
-    # Uses the Matcher class to find the best language match from the list of available languages.
-    #
-    # @param [Array<String, Symbol>] available_langtags An array of language tags that are available for matching.
+    # Finds the best matching language from available options based on user preferences.
+    # Considers quality values and language tag specificity (e.g., "en-US" vs "en").
     #
-    # @example When Uyghur, Kazakh, Russian and English languages are available.
-    #   match(:ug, :kk, :ru, :en)
-    #
-    # @return [String, Symbol, nil] The language tag that best matches the parsed languages from the Accept-Language header, or nil if no match found.
+    # @param [Array<String, Symbol>] available_langtags Languages supported by your application
+    # @return [String, Symbol, nil] Best matching language tag or nil if no match found
+    # @example Match against specific language options
+    #   parser.match("en", "fr", "de") # => "en" if English is preferred
+    # @example Match with region-specific tags
+    #   parser.match("en-US", "en-GB", "fr") # => "en-GB" if British English is preferred
     def match(*available_langtags)
       Matcher.new(**languages_range).call(*available_langtags)
     end
@@ -50,12 +58,22 @@ module AcceptLanguage
     def import(field)
       "#{field}".delete(SPACE).split(SEPARATOR).inject({}) do |hash, lang|
         tag, quality = lang.split(SUFFIX)
-        next hash if tag.nil?
+        next hash unless valid_tag?(tag)
+
+        quality = DEFAULT_QUALITY if quality.nil?
+        next hash unless valid_quality?(quality)
 
-        quality = quality.nil? ? DEFAULT_QUALITY : BigDecimal(quality)
-        hash.merge(tag => quality)
+        hash.merge(tag => BigDecimal(quality))
       end
     end
+
+    def valid_quality?(quality)
+      quality.match?(QVALUE_PATTERN)
+    end
+
+    def valid_tag?(tag)
+      !tag.nil? && !tag.empty?
+    end
   end
 end
 

data/lib/accept_language.rb

@@ -1,13 +1,26 @@
 # frozen_string_literal: true
 
-# This module provides a tiny library for parsing the Accept-Language header as specified in RFC 2616.
-# It transforms the Accept-Language header field into a language range, providing a flexible way to determine
-# user's language preferences and match them with the available languages in your application.
+# AcceptLanguage is a lightweight library that parses Accept-Language HTTP headers (RFC 2616) to determine
+# user language preferences. It converts raw header values into a structured format for matching against
+# your application's supported languages.
 #
 # @example
 #   AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7")
 #   # => #<AcceptLanguage::Parser:0x00007 @languages_range={"da"=>1.0, "en-GB"=>0.8, "en"=>0.7}>
 #
+# @example Integration with Rails
+#   class ApplicationController < ActionController::Base
+#     before_action :set_locale
+#
+#     private
+#
+#     def set_locale
+#       header = request.env["HTTP_ACCEPT_LANGUAGE"]
+#       locale = AcceptLanguage.parse(header).match(*I18n.available_locales)
+#       I18n.locale = locale || I18n.default_locale
+#     end
+#   end
+#
 # @see https://tools.ietf.org/html/rfc2616#section-14.4
 module AcceptLanguage
   # Parses an Accept-Language header field value into a Parser object, which can then be used to match

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: accept_language
 version: !ruby/object:Gem::Version
-  version: 2.0.6
+  version: 2.0.8
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-12 00:00:00.000000000 Z
+date: 2024-12-15 00:00:00.000000000 Z
 dependencies: []
 description: Parses the Accept-Language header from an HTTP request and produces a
   hash of languages and qualities.
@@ -27,7 +27,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -42,8 +42,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
-signing_key: 
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: "Parser for Accept-Language request HTTP header \U0001F310"
 test_files: []