fix(date): apply ISO 8601 (#16)

* fix(date): apply ISO 8601

Author: Arnaud Fernandés

README.md

@@ -3,6 +3,10 @@
 
 Internationalization API
 
+## Breaking changes from 0.2 to 0.3
+- The first day of the week is now Monday according to ISO 8601.
+- The nil value in `month_names` and `abbr_month_names` was removed.
+
 ## Installation
 
 Add this to your application's `shard.yml`:
@@ -101,6 +105,7 @@ I18n.localize(Time.now, scope: :date, format: :long)
 > By default `Time` will be localized with `:time` scope.
 
 To specify formats and all need localization information (like day or month names) fill your file in following way:
+> NOTE: According to ISO 8601, Monday is the first day of the week
 
 ```yaml
 __formats__:
@@ -109,7 +114,6 @@ __formats__:
       default: '%Y-%m-%d' # is used by default
       long: '%A, %d de %B %Y'
     month_names: # long month names
-      -
       - Janeiro
       - Fevereiro
       - Março
@@ -123,16 +127,13 @@ __formats__:
       - Novembro
       - Dezembro
     abbr_month_names: # month abbreviations
-      -
       - Jan
       - Fev
       # ...
     day_names: # fool day names
-      - Domingo
       - Segunda
       # ...
     abbr_day_names: # short day names
-      - Dom
       - Seg
       # ...
 ```
@@ -170,14 +171,16 @@ I18n.translate("message", count: 0) # 0 messages
 
 To store several alternative objects under one localization key they could be just listed in the file and later retrieved using `iter` argument:
 
+> NOTE : The first index is `0`
+
 ```yaml
 __formats__:
   date:
-    day_names: [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]
+    day_names: [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]
 ```
 
 ```crystal
-I18n.translate("__formats__.date.day_names", iter: 2) "Tuesday"
+I18n.translate("__formats__.date.day_names", iter: 2)  # >>> "Wednesday"
 ```
 
 ### Embedding translations inside your binary

shard.yml

@@ -1,9 +1,9 @@
 name: i18n
-version: 0.2.0
+version: 0.3
 
 authors:
   - Arnaud Fernandés <arnaud.fernandes@laposte.net>
 
-crystal: 0.28.0
+crystal: 0.29.0
 
 license: MIT

spec/backend/yaml_spec.cr

@@ -42,7 +42,11 @@ describe I18n::Backend::Yaml do
 
     it { backend.translate("en", "messages.with_2_arguments", {attr: "a", attr2: "b"}).should eq("a and b") }
     it { backend.translate("pt", "hello").should(eq("olá")) }
-    it { backend.translate("pt", "__formats__.date.day_names", iter: 2).should eq("Terça") }
+
+    it {
+      # this usage is not recommended
+      backend.translate("pt", "__formats__.date.day_names", iter: 1).should eq("Terça")
+    }
   end
 
   describe "#localize" do
@@ -62,17 +66,17 @@ describe I18n::Backend::Yaml do
 
     context "with time format" do
       it "time default format" do
-        backend.localize("pt", time, scope: :time).should(eq(time.to_s("%H:%M:%S")))
+        backend.localize("pt", time, scope: :time).should(eq("12:13:14"))
       end
     end
 
     context "with date format" do
       it "date default format" do
-        backend.localize("pt", time, scope: :date).should(eq(time.to_s("%Y-%m-%d")))
+        backend.localize("pt", time, scope: :date).should(eq("2010-10-11"))
       end
 
       it "date long format" do
-        backend.localize("en", time, scope: :date, format: "long").should(eq(time.to_s("%A, %d of %B %Y")))
+        backend.localize("pt", time, scope: :date, format: "long").should(eq("Segunda, 11 de Outubro 2010"))
       end
     end
 

spec/i18n_spec.cr

@@ -34,7 +34,7 @@ describe I18n do
   end
 
   describe ".localize" do
-    time = Time.now
+    time = Time.local(2019, 7, 14, 20, 1, 3)
 
     it "format number" do
       I18n.localize(1234).should(eq("1.234"))
@@ -49,18 +49,18 @@ describe I18n do
     end
 
     it "time default format" do
-      I18n.localize(time, scope: :time).should(eq(time.to_s("%H:%M:%S")))
+      I18n.localize(time, scope: :time).should(eq("20:01:03"))
     end
 
     it "date default format" do
-      I18n.localize(time, scope: :date).should(eq(time.to_s("%Y-%m-%d")))
+      I18n.localize(time, scope: :date).should(eq("2019-07-14"))
     end
 
     it "date long format" do
-      I18n.localize(time, scope: :date, force_locale: "en", format: "long").should(eq(time.to_s("%A, %d of %B %Y")))
+      I18n.localize(time, scope: :date, force_locale: "en", format: "long").should(eq("Sunday, 14 of July 2019"))
     end
 
-    it { I18n.localize(time, "en", :date, "long").should(eq(time.to_s("%A, %d of %B %Y"))) }
+    it { I18n.localize(time, "en", :date, "long").should(eq("Sunday, 14 of July 2019")) }
   end
 
   describe ".with_locale" do

spec/locales/en.yml

@@ -23,11 +23,11 @@ __formats__:
             default: "%Y-%m-%d"
             long: "%A, %d of %B %Y"
 
-        month_names: [~, January, February, March, April, May, June, July, August, September, October, November, December]
-        abbr_month_names: [~, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
+        month_names: [January, February, March, April, May, June, July, August, September, October, November, December]
+        abbr_month_names: [Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
 
-        day_names: [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]
-        abbr_day_names: [Sun, Mon, Tue, Wed, Thu, Fri, Sat]
+        day_names: [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]
+        abbr_day_names: [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
 
     time:
         formats:

spec/locales/pt.yml

@@ -17,7 +17,6 @@ __formats__:
         default: '%Y-%m-%d'
         long: '%A, %d de %B %Y'
       month_names:
-        -
         - Janeiro
         - Fevereiro
         - Março
@@ -31,7 +30,6 @@ __formats__:
         - Novembro
         - Dezembro
       abbr_month_names:
-        -
         - Jan
         - Fev
         - Mar
@@ -45,21 +43,21 @@ __formats__:
         - Nov
         - Dez
       day_names:
-        - Domingo
         - Segunda
         - Terça
         - Quarta
         - Quinta
         - Sexta
         - Sábado
+        - Domingo
       abbr_day_names:
-        - Dom
         - Seg
         - Ter
         - Qua
         - Qui
         - Sex
         - Sáb
+        - Dom
     time:
       formats:
         default: '%H:%M:%S'

src/i18n/backend/yaml.cr

@@ -21,6 +21,7 @@ module I18n
         {% end %}
       end
 
+      # Read files, normalize and merge all the translations
       def load(*args)
         if args[0].is_a?(String)
           files = Dir.glob(args[0] + "/*.yml")
@@ -67,9 +68,11 @@ module I18n
 
       # Localize a number or a currency
       # Use the format if given
-      # scope can be one of :number ( default ), :currency
+      # scope can be one of `:number` ( default ), `:currency`
+      #
       # Following keys are required :
       #
+      # ```yaml
       # __formats__:
       #       number:
       #         decimal_separator: ','
@@ -79,6 +82,7 @@ module I18n
       #         symbol: '€'
       #       name: 'euro'
       #       format: '%s€'
+      # ```
       def localize(locale : String, object : Number, scope = :number, format = nil) : String
         return object.to_s if scope != :number && scope != :currency
 
@@ -90,36 +94,39 @@ module I18n
         number
       end
 
-      # Localize a date or a datetime
-      # Use the format if given
-      # scope can be one of :time ( default ), :date, :datetime
-      # Following keys are required :
+      # Localize a date or a datetime using the *format* if provided.
+      # *scope* can be one of :time ( default ), :date, :datetime
       #
+      # NOTE: According to ISO 8601, Monday is the first day of the week
+      #
+      # Following keys are required :
+      # ```yaml
       # __formats__:
       #       date:
       #         formats:
       #         default: "%Y-%m-%d"
       #       long: "%A, %d of %B %Y"
       #
-      #       month_names: [~, January, February, March, April, May, June, July, August, September, October, November, December]
-      #       abbr_month_names: [~, Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
+      #       month_names: [January, February, March, April, May, June, July, August, September, October, November, December]
+      #       abbr_month_names: [Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec]
       #
-      #       day_names: [Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]
-      #       abbr_day_names: [Sun, Mon, Tue, Wed, Thu, Fri, Sat]
+      #       day_names: [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]
+      #       abbr_day_names: [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
       #
       #       time:
       #         formats:
       #             default: "%I:%M:%S %p"
+      # ```
       def localize(locale : String, object : Time, scope = :time, format = nil) : String
         base_key = "__formats__." + scope.to_s + (format ? ".formats." + format.to_s : ".formats.default")
 
         format = translate(locale, base_key)
         format = format.to_s.gsub(/%[aAbBpP]/) do |match|
           case match
-          when "%a" then translate(locale, "__formats__.date.abbr_day_names", iter: object.day_of_week.to_i)
-          when "%A" then translate(locale, "__formats__.date.day_names", iter: object.day_of_week.to_i)
-          when "%b" then translate(locale, "__formats__.date.abbr_month_names", iter: object.month)
-          when "%B" then translate(locale, "__formats__.date.month_names", iter: object.month)
+          when "%a" then translate(locale, "__formats__.date.abbr_day_names", iter: object.day_of_week.value - 1)
+          when "%A" then translate(locale, "__formats__.date.day_names", iter: object.day_of_week.value - 1)
+          when "%b" then translate(locale, "__formats__.date.abbr_month_names", iter: object.month - 1)
+          when "%B" then translate(locale, "__formats__.date.month_names", iter: object.month - 1)
           when "%p" then translate(locale, "__formats__.time.#{object.hour < 12 ? :am : :pm}").upcase if object.responds_to? :hour
           when "%P" then translate(locale, "__formats__.time.#{object.hour < 12 ? :am : :pm}").downcase if object.responds_to? :hour
           end
@@ -182,6 +189,7 @@ module I18n
         end
       end
 
+      # Flatten paths
       def self.normalize(data : YAML::Any, path : String = "", final = Hash(String, YAML::Any).new)
         data.as_h.keys.each do |k|
           newp = path.size == 0 ? k.to_s : path + "." + k.to_s