accept_language 2.1.0 → 2.2.0

data/lib/accept_language.rb

@@ -1,27 +1,267 @@
 # frozen_string_literal: true
 
-# AcceptLanguage is a lightweight library for parsing Accept-Language HTTP headers
-# as defined in RFC 2616. It determines user language preferences and matches them
-# against your application's supported languages.
+# = Accept-Language Header Parser
 #
-# @example Basic usage
+# AcceptLanguage is a lightweight, thread-safe Ruby library for parsing the
+# +Accept-Language+ HTTP header field as defined in RFC 2616 Section 14.4,
+# with full support for BCP 47 (RFC 5646) language tags.
+#
+# == Purpose
+#
+# The +Accept-Language+ request-header field is sent by user agents to indicate
+# the set of natural languages that are preferred as a response to the request.
+# This library parses that header and matches the user's language preferences
+# against your application's available languages, respecting quality values,
+# wildcards, exclusions, and prefix matching rules defined by the HTTP/1.1
+# specification.
+#
+# == Standards Compliance
+#
+# This implementation conforms to:
+#
+# - {RFC 2616 Section 14.4}[https://tools.ietf.org/html/rfc2616#section-14.4] -
+#   Accept-Language header field definition
+# - {RFC 2616 Section 3.9}[https://tools.ietf.org/html/rfc2616#section-3.9] -
+#   Quality values (qvalues) syntax
+# - {RFC 2616 Section 3.10}[https://tools.ietf.org/html/rfc2616#section-3.10] -
+#   Language tags reference
+# - {BCP 47 / RFC 5646}[https://tools.ietf.org/html/bcp47] -
+#   Tags for Identifying Languages (modern standard for language tags)
+#
+# == Basic Usage
+#
+#   require "accept_language"
+#
+#   # Parse an Accept-Language header and find the best match
 #   AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :da)
 #   # => :da
 #
-# @example With regional variants
+#   # With regional variants
 #   AcceptLanguage.parse("fr-CH, fr;q=0.9").match(:fr, :"fr-CH")
 #   # => :"fr-CH"
 #
-# @see https://tools.ietf.org/html/rfc2616#section-14.4
+#   # When no match is found
+#   AcceptLanguage.parse("ja, zh;q=0.9").match(:en, :fr)
+#   # => nil
+#
+# == Quality Values
+#
+# Quality values (q-values) express relative preference, ranging from +0+
+# (explicitly unacceptable) to +1+ (most preferred). When omitted, the
+# default quality value is +1+.
+#
+# Per RFC 2616 Section 3.9, valid q-values have at most three decimal places.
+# Invalid q-values cause the associated language tag to be ignored.
+#
+#   parser = AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7")
+#
+#   parser.match(:en, :da)      # => :da       (q=1 beats q=0.8)
+#   parser.match(:en, :"en-GB") # => :"en-GB"  (q=0.8 beats q=0.7)
+#
+# == Prefix Matching
+#
+# Per RFC 2616 Section 14.4, a language-range matches a language-tag if it
+# exactly equals the tag, or if it exactly equals a prefix of the tag such
+# that the first character following the prefix is a hyphen (+"-"+).
+#
+#   # "zh" matches "zh-TW" (prefix match)
+#   AcceptLanguage.parse("zh").match(:"zh-TW")
+#   # => :"zh-TW"
+#
+#   # "zh-TW" does NOT match "zh" (more specific cannot match less specific)
+#   AcceptLanguage.parse("zh-TW").match(:zh)
+#   # => nil
+#
+#   # Prefix matching respects hyphen boundaries
+#   AcceptLanguage.parse("zh").match(:zhx)
+#   # => nil  (zhx is a different language code, not a subtag of zh)
+#
+# == Wildcards
+#
+# The wildcard character +*+ matches any language not explicitly matched by
+# another language-range in the header:
+#
+#   # Wildcard matches any language
+#   AcceptLanguage.parse("de, *;q=0.5").match(:ja)
+#   # => :ja
+#
+#   # Explicit matches take precedence over wildcard
+#   AcceptLanguage.parse("de, *;q=0.5").match(:de, :ja)
+#   # => :de
+#
+# == Exclusions
+#
+# A quality value of +0+ explicitly marks a language as unacceptable:
+#
+#   # English is excluded despite wildcard
+#   AcceptLanguage.parse("*, en;q=0").match(:en)
+#   # => nil
+#
+#   AcceptLanguage.parse("*, en;q=0").match(:ja)
+#   # => :ja
+#
+#   # Exclusions apply to prefix matches
+#   AcceptLanguage.parse("*, en;q=0").match(:"en-GB")
+#   # => nil  (en-GB is excluded via the "en" prefix)
+#
+# == Priority with Equal Quality Values
+#
+# When multiple languages share the same quality value, declaration order in
+# the original header determines priority—the first declared language wins:
+#
+#   AcceptLanguage.parse("en;q=0.8, fr;q=0.8").match(:en, :fr)
+#   # => :en  (declared first)
+#
+#   AcceptLanguage.parse("fr;q=0.8, en;q=0.8").match(:en, :fr)
+#   # => :fr  (declared first)
+#
+# == Case Insensitivity
+#
+# Language tag matching is case-insensitive per RFC 2616, but the original
+# case of available language tags provided to +match+ is preserved in the
+# return value:
+#
+#   AcceptLanguage.parse("EN-GB").match(:"en-gb")
+#   # => :"en-gb"
+#
+#   AcceptLanguage.parse("en-gb").match(:"EN-GB")
+#   # => :"EN-GB"
+#
+# == BCP 47 Language Tags
+#
+# Full support for BCP 47 language tags including script subtags, region
+# subtags, and variant subtags:
+#
+#   # Script subtags (e.g., Hans for Simplified Chinese)
+#   AcceptLanguage.parse("zh-Hant").match(:"zh-Hant-TW", :"zh-Hans-CN")
+#   # => :"zh-Hant-TW"
+#
+#   # Variant subtags (e.g., 1996 for German orthography reform)
+#   AcceptLanguage.parse("de-1996, de;q=0.9").match(:"de-CH-1996", :"de-CH")
+#   # => :"de-CH-1996"
+#
+# == Thread Safety
+#
+# All AcceptLanguage operations are thread-safe. Parser instances are
+# immutable after initialization and can be safely shared between threads.
+#
+# == Rack Integration Example
+#
+#   # config.ru
+#   class LocaleMiddleware
+#     def initialize(app, available_locales:, default_locale:)
+#       @app = app
+#       @available_locales = available_locales
+#       @default_locale = default_locale
+#     end
+#
+#     def call(env)
+#       locale = detect_locale(env) || @default_locale
+#       env["rack.locale"] = locale
+#       @app.call(env)
+#     end
+#
+#     private
+#
+#     def detect_locale(env)
+#       header = env["HTTP_ACCEPT_LANGUAGE"]
+#       AcceptLanguage.parse(header).match(*@available_locales)
+#     end
+#   end
+#
+# == Rails Integration Example
+#
+#   # app/controllers/application_controller.rb
+#   class ApplicationController < ActionController::Base
+#     before_action :best_locale_from_request!
+#
+#     def best_locale_from_request!
+#       I18n.locale = best_locale_from_request
+#     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")
+#       locale = AcceptLanguage.parse(string).match(*I18n.available_locales)
+#
+#       # If the server cannot serve any matching language,
+#       # it can theoretically send back a 406 (Not Acceptable) error code.
+#       # But, for a better user experience, this is rarely done and more
+#       # common way is to ignore the Accept-Language header in this case.
+#       return I18n.default_locale if locale.nil?
+#
+#       locale
+#     end
+#   end
+#
+# @see Parser
+# @see https://tools.ietf.org/html/rfc2616#section-14.4 RFC 2616 Section 14.4
+# @see https://tools.ietf.org/html/bcp47 BCP 47
+# @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language MDN Accept-Language
+#
+# @author Cyril Kato
+# @since 1.0.0
 module AcceptLanguage
-  # Parses an Accept-Language header field value.
+  # Parses an +Accept-Language+ header field value and returns a parser
+  # instance that can be used to match against available languages.
+  #
+  # The parser handles all aspects of the Accept-Language specification:
+  # - Quality values (+q=0+ to +q=1+, default +1+ when omitted)
+  # - Language tag validation per BCP 47
+  # - Wildcards (+*+)
+  # - Case normalization (matching is case-insensitive)
+  #
+  # Invalid language tags or malformed quality values in the input are
+  # silently ignored, allowing the parser to handle real-world headers
+  # that may not strictly conform to specifications.
+  #
+  # @param field [String, nil] the Accept-Language header field value.
+  #   Typically obtained from +request.headers["HTTP_ACCEPT_LANGUAGE"]+ in
+  #   Rails or +env["HTTP_ACCEPT_LANGUAGE"]+ in Rack applications.
+  #   When +nil+ is passed (header absent), it is treated as an empty string,
+  #   resulting in a parser that matches no languages.
+  #
+  # @return [Parser] a parser instance configured with the language preferences
+  #   from the header. Call {Parser#match} on this instance to find the best
+  #   matching language from your available options.
+  #
+  # @raise [TypeError] if +field+ is neither a String nor +nil+
+  #
+  # @example Basic parsing and matching
+  #   parser = AcceptLanguage.parse("en-GB, en;q=0.9, fr;q=0.8")
+  #   parser.match(:en, :"en-GB", :fr)
+  #   # => :"en-GB"
+  #
+  # @example Handling missing or empty headers
+  #   AcceptLanguage.parse("").match(:en, :fr)
+  #   # => nil
+  #
+  #   AcceptLanguage.parse(nil).match(:en, :fr)
+  #   # => nil
+  #
+  # @example Reusing a parser instance
+  #   # Parse once, match multiple times
+  #   user_prefs = AcceptLanguage.parse(header_value)
+  #
+  #   # Match for UI language
+  #   ui_locale = user_prefs.match(*available_ui_locales)
+  #
+  #   # Match for content language
+  #   content_locale = user_prefs.match(*available_content_locales)
+  #
+  # @example Handling edge cases
+  #   # Invalid q-values are ignored
+  #   AcceptLanguage.parse("en;q=2.0, fr;q=0.8").match(:en, :fr)
+  #   # => :fr  (en is ignored due to invalid q-value > 1)
   #
-  # @param field [String] The Accept-Language header field value
-  # @return [Parser] A parser object that responds to {Parser#match}
+  #   # Invalid language tags are ignored
+  #   AcceptLanguage.parse("123invalid, fr;q=0.8").match(:fr)
+  #   # => :fr
   #
-  # @example
-  #   parser = AcceptLanguage.parse("en-GB, en;q=0.9")
-  #   parser.match(:en, :"en-GB") # => :"en-GB"
+  # @see Parser#match
+  # @see https://tools.ietf.org/html/rfc2616#section-14.4 RFC 2616 Section 14.4
   def self.parse(field)
     Parser.new(field)
   end

metadata

@@ -1,31 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: accept_language
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-15 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bigdecimal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Parses the Accept-Language header from an HTTP request and produces a
-  hash of languages and qualities.
+date: 2026-01-20 00:00:00.000000000 Z
+dependencies: []
+description: A lightweight, thread-safe Ruby library for parsing the Accept-Language
+  HTTP header as defined in RFC 2616, with full support for BCP 47 language tags.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -41,6 +27,10 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/cyril/accept_language.rb
+  documentation_uri: https://rubydoc.info/github/cyril/accept_language.rb/main
+  bug_tracker_uri: https://github.com/cyril/accept_language.rb/issues
+  wiki_uri: https://github.com/cyril/accept_language.rb/wiki
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -59,5 +49,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: "Parser for Accept-Language request HTTP header \U0001F310"
+summary: Parser for Accept-Language request HTTP header
 test_files: []