preferred_locale 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25d7d501311ec07eb4453107066175a7ff0d34493084cc3e8d0b38864147ff3e
-  data.tar.gz: 8bf555fc4424a836839253ba9b88c1f464d2be7d97d1d7c7f20b07ee03ac8f39
+  metadata.gz: 9b3dd0a6d6efe6ee0a04861617f18a144ca0055416e8625f332927656d1af7dc
+  data.tar.gz: 19a440f91a0cc1c84a017e7fdb9c53d7e1031111229bc5d11daad613bcf4c71a
 SHA512:
-  metadata.gz: b306fd65e2dfe7203705a4904b9ba5df4eb370695aa453ecb8685df8201ddc358736a200a515cd2afad41025a628c5f0bec7162087e1b8f499ad8203a5698ab1
-  data.tar.gz: 67a93005c500cc999f628a0b016ae9454b55bb8cf64c4cff65597cc9a7b08b24340ecd9336223bc61607362d3608f0c85b6e47d007094cd0dedeee2b6411c208
+  metadata.gz: a03628fe5782f91dc4d0f451ddb9362a15494e5b71c6b69bd301e5f33283059ea7f30552f7dcde0365600eadcf261be2ba1fad2944f22d6c0aea58bab40f6cad
+  data.tar.gz: fa21679df9523936a3695e06dc37320bad283eda0acb1f1bb6f1351b1c2cd1f671b55fc1a7e4a493d6ccd08cb61a1986da91acfaa0a9503e28327306bf04d705

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
-## [1.0.0] - 2023-05-05
+## [1.1.0](https://github.com/hummingbird-me/preferred_locale/releases/tag/v1.1.0) - 2023-05-06
+
+- Improve documentation
+- Don't add an implicit (language) fallback if the language is explicitly provided elsewhere in a
+  list. For example, if `en-US` and `en` are both in the list, don't add `en` as a fallback for
+  `en-US`.
+
+## [1.0.0](https://github.com/hummingbird-me/preferred_locale/releases/tag/v1.0.0) - 2023-05-05
 
 - Initial release

data/Gemfile

@@ -10,3 +10,4 @@ gem 'rspec'
 gem 'rubocop'
 gem 'rubocop-performance'
 gem 'rubocop-rspec'
+gem 'simplecov'

data/Gemfile.lock

@@ -1,13 +1,14 @@
 PATH
   remote: .
   specs:
-    preferred_locale (1.0.0)
+    preferred_locale (1.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
     diff-lcs (1.5.0)
+    docile (1.4.0)
     json (2.6.3)
     parallel (1.23.0)
     parser (3.2.2.1)
@@ -50,6 +51,12 @@ GEM
       rubocop (~> 1.33)
       rubocop-capybara (~> 2.17)
     ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
     unicode-display_width (2.4.2)
 
 PLATFORMS
@@ -64,6 +71,7 @@ DEPENDENCIES
   rubocop
   rubocop-performance
   rubocop-rspec
+  simplecov
 
 BUNDLED WITH
    2.3.13

data/README.md

@@ -5,6 +5,42 @@ practice, this usually means finding the best locale between `I18n.available_loc
 `Accept-Language` header from the request, but it could also be used to find the best locale between
 something in your database and a user's preferences.
 
+This is similar to the [http_accept_language gem](https://github.com/iain/http_accept_language) and
+the [preferred-locale JS library](https://github.com/wopian/preferred-locale) in that it attempts to
+resolve mismatches in specificity (ie, `en-US` vs `en`), but differs slightly in algorithm and in
+API design.
+
+## Algorithm
+
+For available locales from the application:
+
+1. Start with available locales:
+   - `['en-US', 'pt-BR', 'ja-JP', 'pt']`
+2. Normalize them to lowercase mapped to the original values:
+   - `{'en-us' => 'en-US', 'pt-br' => 'pt-BR', 'ja-jp' => 'ja-JP', 'pt' => 'pt'}`
+3. Add "implicit" locales as fallbacks:
+   - `{'en-us' => 'en-US', 'en' => 'en-US', 'pt-br' => 'pt-BR', 'ja-jp' => 'ja-JP', 'ja' => 'ja-JP',
+     'pt' => 'pt'}`
+   - Note that `en` and `ja` are added as fallbacks for `en-US` and `ja-JP` respectively, but *not*
+     for `pt-BR` because `pt` is already in the list later.
+
+Now to match a user's preferred locales:
+
+1. Start with preferred locales:
+   - `['en-US', 'fr', 'ja-JP', 'en']`
+2. Normalize them to lowercase:
+   - `['en-us', 'fr', 'ja-jp', 'en']`
+3. Add "implicit" locales as fallbacks:
+   - `['en-us', 'fr', 'ja-jp', 'ja', 'en']`
+   - As above, note that `en` is *not* added as a fallback for `en-us` because it is already in the
+     list.
+4. Filter out locales that are not available:
+   - `['en-us', 'ja-jp', 'ja', 'en']`
+5. Convert to the canonical form
+   - `['en-US', 'ja-JP', 'ja-JP', 'en-US']`
+6. Remove duplicates
+   - `['en-US', 'ja-JP']`
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -30,13 +66,13 @@ preferred_locale = PreferredLocale.new(available: ['en', 'fr', 'es'])
 Then, you can find the available locales from a given list of locales from the user:
 
 ```ruby
-preferred_locale.acceptable_for(['en-US', 'fr', 'ja-JP']) # => ['en', 'fr']
+preferred_locale.acceptable_for(locales: ['en-US', 'fr', 'ja-JP']) # => ['en', 'fr']
 ```
 
 Or you can just get the best one:
 
 ```ruby
-preferred_locale.preferred_for(['en-US', 'fr', 'ja-JP']) # => 'en'
+preferred_locale.preferred_for(locales: ['en-US', 'fr', 'ja-JP']) # => 'en'
 ```
 
 ### With Rails

data/lib/preferred_locale/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class PreferredLocale
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/lib/preferred_locale.rb

@@ -15,14 +15,20 @@ class PreferredLocale
       obj[locale_str.downcase] = locale
       # Add the language without a country if it's not already in the list
       language = locale_str.downcase.split('-')[0]
-      obj[language] = locale unless available_lower.include?(language)
+      obj[language] = locale unless available_lower.include?(language) || obj.key?(language)
     end
   end
 
   def acceptable_for(locales: [])
+    locales_lower = locales.map { |locale| locale.to_s.downcase }
     # Build a candidate list including our implicit candidate locales
-    candidates = locales.flat_map do |locale|
-      [locale.to_s.downcase, locale.to_s.split('-')[0].downcase]
+    candidates = locales_lower.flat_map do |locale|
+      language = locale.split('-')[0]
+      [
+        locale,
+        # Add the language without a country if it's not already in the list
+        (language unless locales_lower.include?(language))
+      ].compact
     end
 
     # Figure out which candidates are available

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: preferred_locale
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Emma Lejeck
@@ -37,6 +37,7 @@ metadata:
   homepage_uri: https://github.com/hummingbird-me/preferred_locale
   source_code_uri: https://github.com/hummingbird-me/preferred_locale
   changelog_uri: https://github.com/hummingbird-me/preferred_locale/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths: