worldwide 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c088cf8b57df5d8d9de377cee8b3b0e29517c5b997fe0bf70ee3b8970499f97d
-  data.tar.gz: 90ae4641252f4a7f2a8262794782f7287fc176253cf62047f24a24e447580a56
+  metadata.gz: 1aced99de70bc88aa872fd56bf0aea847c81bcf3b12987e031ce39a51e9dbdd0
+  data.tar.gz: de70d75e3374938d1611ef3c0541ce7d880d4dbf5ad3b45fb4dddeeb6ef75382
 SHA512:
-  metadata.gz: 0156d547c2c0fba8c5d7b89bde2cdc441a05e8dceb7285cf990e6b79cbd1d7d6564e52a8cc5ce873e247147ed7caeeaf2f28515f047146b5c200a041548edb0e
-  data.tar.gz: '09cbfa47fd5e9b79dbb129cda279d2da44aa98f7bfc3800439830fbdfbb4d1bfb9cba420d25530679f24c7d91af47975a6e6bdc25633fddf3d8e4c7dfad077e5'
+  metadata.gz: e77fdb3041498e31ab8cec400ca4be14e531939e9f99fa800aae011d1a7be0e076fc6b4e65ea4ca877b98a051dc6e88994b71d27582cb083fb8c71ac0645e65f
+  data.tar.gz: bb7c2b6963ab30589320b70db8af56942ce454d01cbf6dc7f13c7da74c86964513de2711a31bd9fa07457e96fcb810f482d89e31a214acf5454f47ec21517dfc

data/CHANGELOG.md

@@ -27,10 +27,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
-- Nil.
-
 ---
 
+## [0.12.0] - 2024-05-15
+
+- Add pry-byebug gem [#149](https://github.com/Shopify/worldwide/pull/149)
+- Introduce additional_address_fields to Region class and define them for BE, BR, CL, CO, ES, ID, MX, NL, PH, TR, VN [#148](https://github.com/Shopify/worldwide/pull/148)
+- Define format_extended attribute on 12 country regions [#150](https://github.com/Shopify/worldwide/pull/150)
+
+## [0.11.1] - 2024-05-13
+
+- Handle blank strings for Region, country_code parameter in Zip normalization
+  [#138](https://github.com/Shopify/worldwide/pull/138)
+- Reposition zip in NF show: format to come after country, not before city. [#142](https://github.com/Shopify/worldwide/pull/142)
+- Allow building number on address2 for CH [#143](https://github.com/Shopify/worldwide/pull/143)
+- Attempt to fix stringio incompatibility with Ruby 3.3 (deployment error) [#145](https://github.com/Shopify/worldwide/pull/145)
+
 ## [0.11.0] - 2024-04-11
 
 - Add country_prefix to phone [#133](https://github.com/Shopify/worldwide/pull/133)

data/Gemfile

@@ -19,6 +19,7 @@ group :development do
   gem "rubocop-shopify", require: false
   gem "rubocop", require: false
   gem "ruby-lsp", require: false
+  gem "pry-byebug", require: false
 end
 
 group :test do

data/Gemfile.lock

@@ -13,7 +13,7 @@ GIT
 PATH
   remote: .
   specs:
-    worldwide (0.11.0)
+    worldwide (0.12.0)
       activesupport (~> 7.0)
       i18n
       phonelib (~> 0.8)
@@ -36,6 +36,8 @@ GEM
     base64 (0.1.1)
     bigdecimal (3.1.4)
     builder (3.2.4)
+    byebug (11.1.3)
+    coderay (1.1.3)
     concurrent-ruby (1.2.2)
     connection_pool (2.4.1)
     drb (2.1.1)
@@ -44,6 +46,7 @@ GEM
       concurrent-ruby (~> 1.0)
     json (2.7.1)
     language_server-protocol (3.17.0.3)
+    method_source (1.1.0)
     minitest (5.17.0)
     minitest-focus (1.3.1)
       minitest (>= 4, < 6)
@@ -55,9 +58,9 @@ GEM
     mocha (2.0.2)
       ruby2_keywords (>= 0.0.5)
     mutex_m (0.1.2)
-    nokogiri (1.16.2-arm64-darwin)
+    nokogiri (1.16.5-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.2-x86_64-linux)
+    nokogiri (1.16.5-x86_64-linux)
       racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.0.5)
@@ -65,6 +68,12 @@ GEM
       racc
     phonelib (0.8.7)
     prettier_print (1.2.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
     psych (5.1.0)
       stringio
     racc (1.7.3)
@@ -104,7 +113,7 @@ GEM
     ruby2_keywords (0.0.5)
     rubyzip (2.3.2)
     sorbet-runtime (0.5.10648)
-    stringio (3.0.6)
+    stringio (3.1.0)
     syntax_tree (5.3.0)
       prettier_print (>= 1.2.0)
     thor (1.2.1)
@@ -122,6 +131,7 @@ DEPENDENCIES
   minitest-focus
   minitest-reporters
   mocha
+  pry-byebug
   rake (~> 13.0)
   rake-compiler
   rubocop

data/README.md

@@ -377,6 +377,8 @@ $ I18n.with_locale(:'zh-CN') { lon.single_line }
 => "英国London"
 ```
 
+Address format strings are described in detail [here](docs/address_format_strings.md).
+
 #### Validation
 
 ```ruby

data/db/data/regions/BE.yml

@@ -24,5 +24,13 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}_{zip}{city}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
 emoji: "\U0001F1E7\U0001F1EA"
 timezone: Europe/Brussels

data/db/data/regions/BR.yml

@@ -19,6 +19,21 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{zip}_{address1}_{address2}_{city}{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city} {province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{zip}_{streetName}{streetNumber}_{address2}{neighborhood}_{city}{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      decorator: ","
+      required: true
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: ","
+      required: false
 emoji: "\U0001F1E7\U0001F1F7"
 localized_data:
 - name: tax_credential_br

data/db/data/regions/CH.yml

@@ -14,6 +14,7 @@ zip_example: '2544'
 zip_regex: "^((CH( |-)?)?(([1-8]\\d{3})|(9[012356789]\\d{2})|(94[01234567]\\d)))$"
 phone_number_prefix: 41
 building_number_required: true
+building_number_may_be_in_address2: true
 week_start_day: monday
 languages:
   - de

data/db/data/regions/CL/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    CL:
+      addresses:
+        neighborhood:
+          label:
+            default: Commune
+            optional: Commune (optional)
+          errors:
+            blank: Enter a commune
+            too_long: Commune is too long (maximum is 255 characters)
+            contains_emojis: Commune cannot contain emojis
+            contains_mathematical_symbols: Commune cannot contain mathematical symbols
+            contains_restricted_characters: Commune can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Commune cannot have more than %{word_count}
+              words
+            contains_html_tags: Commune cannot contain HTML tags.
+            contains_url: Commune cannot contain URLs.
+            unknown_for_city: Enter a valid commune name for %{city}.
+            unknown_for_zip: Enter a valid commune name for %{zip}.
+            unknown_for_address: Commune may be incorrect.
+          warnings:
+            contains_too_many_words: Commune is recommended to have less than %{word_count} words

data/db/data/regions/CL.yml

@@ -14,6 +14,19 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}{neighborhood}_{zip}{city}_{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: false
 emoji: "\U0001F1E8\U0001F1F1"
 languages:
   - es

data/db/data/regions/CO.yml

@@ -15,6 +15,14 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}{province}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city} {province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{city}{province}{zip}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: false
 emoji: "\U0001F1E8\U0001F1F4"
 languages:
   - es

data/db/data/regions/ES.yml

@@ -21,6 +21,14 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}_{zip}{city}{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
 emoji: "\U0001F1EA\U0001F1F8"
 zones:
 - name: A Coruña

data/db/data/regions/ID.yml

@@ -17,6 +17,15 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}_{province}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{city}_{province} {zip}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{city}_{province}{zip}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: ","
+      required: false
 emoji: "\U0001F1EE\U0001F1E9"
 zones:
 - name: Aceh

data/db/data/regions/IN.yml

@@ -141,8 +141,8 @@ zones:
   zip_prefixes:
   - '49'
   # Dadra and Nagar Haveli was merged with Daman and Diu in 2020, and uses the new ISO code DH for the combined zone.
-  # But, we need to upgrade our version of CLDR before shopify-i18n will recognize DH.
-  # TODO:  import new CLDR in shopify-i18n, merge DD and DN into new zone DH
+  # But, we need to upgrade our version of CLDR before worldwide will recognize DH.
+  # TODO:  import new CLDR in worldwide, merge DD and DN into new zone DH
 - name: Dadra and Nagar Haveli
   code: DN
   tax: 0.18

data/db/data/regions/MX.yml

@@ -15,6 +15,19 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city} {province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}{neighborhood}_{zip}{city}{province}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: false
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: true
 emoji: "\U0001F1F2\U0001F1FD"
 languages:
   - es

data/db/data/regions/NF.yml

@@ -12,7 +12,7 @@ phone_number_prefix: 672
 zip_autofill_enabled: true
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}_{phone}"
-  show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+  show: "{firstName} {lastName}_{company}_{address1}_{address2}_{city}_{country} {zip}_{phone}"
 emoji: 🇳🇫
 languages:
   - en

data/db/data/regions/NL.yml

@@ -23,5 +23,13 @@ languages:
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{streetName}{streetNumber}_{address2}_{zip}{city}_{phone}"
+additional_address_fields:
+  address1:
+    - key: streetName
+      required: true
+    - key: streetNumber
+      required: true
 emoji: "\U0001F1F3\U0001F1F1"
 timezone: Europe/Amsterdam

data/db/data/regions/PH.yml

@@ -15,6 +15,15 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{province}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{province}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{zip}{city}_{province}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: "Barangay"
+      required: true
 emoji: "\U0001F1F5\U0001F1ED"
 languages:
   - en

data/db/data/regions/TR/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    TR:
+      addresses:
+        neighborhood:
+          label:
+            default: District
+            optional: District (optional)
+          errors:
+            blank: Enter a district
+            too_long: District is too long (maximum is 255 characters)
+            contains_emojis: District cannot contain emojis
+            contains_mathematical_symbols: District cannot contain mathematical symbols
+            contains_restricted_characters: District can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: District cannot have more than %{word_count}
+              words
+            contains_html_tags: District cannot contain HTML tags.
+            contains_url: District cannot contain URLs.
+            unknown_for_city: Enter a valid district name for %{city}.
+            unknown_for_zip: Enter a valid district name for %{zip}.
+            unknown_for_address: District may be incorrect.
+          warnings:
+            contains_too_many_words: District is recommended to have less than %{word_count} words

data/db/data/regions/TR.yml

@@ -16,6 +16,14 @@ week_start_day: monday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{zip}{city}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}{neighborhood}_{zip}{city}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      required: false
 emoji: "\U0001F1F9\U0001F1F7"
 languages:
   - tr

data/db/data/regions/TW/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    TW:
+      addresses:
+        neighborhood:
+          label:
+            default: District
+            optional: District (optional)
+          errors:
+            blank: Enter a district
+            too_long: District is too long (maximum is 255 characters)
+            contains_emojis: District cannot contain emojis
+            contains_mathematical_symbols: District cannot contain mathematical symbols
+            contains_restricted_characters: District can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: District cannot have more than %{word_count}
+              words
+            contains_html_tags: District cannot contain HTML tags.
+            contains_url: District cannot contain URLs.
+            unknown_for_city: Enter a valid district name for %{city}.
+            unknown_for_zip: Enter a valid district name for %{zip}.
+            unknown_for_address: District may be incorrect.
+          warnings:
+            contains_too_many_words: District is recommended to have less than %{word_count} words

data/db/data/regions/TW.yml

@@ -17,6 +17,8 @@ week_start_day: sunday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{zip} {city}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{neighborhood}{city}{zip}_{phone}"
 emoji: "\U0001F1F9\U0001F1FC"
 languages:
   - "zh-TW"

data/db/data/regions/VN/en.yml

@@ -0,0 +1,25 @@
+---
+en:
+  worldwide:
+    VN:
+      addresses:
+        neighborhood:
+          label:
+            default: Ward
+            optional: Ward (optional)
+          errors:
+            blank: Enter a ward
+            too_long: Ward is too long (maximum is 255 characters)
+            contains_emojis: Ward cannot contain emojis
+            contains_mathematical_symbols: Ward cannot contain mathematical symbols
+            contains_restricted_characters: Ward can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Ward cannot have more than %{word_count}
+              words
+            contains_html_tags: Ward cannot contain HTML tags.
+            contains_url: Ward cannot contain URLs.
+            unknown_for_city: Enter a valid ward name for %{city}.
+            unknown_for_zip: Enter a valid ward name for %{zip}.
+            unknown_for_address: Ward may be incorrect.
+          warnings:
+            contains_too_many_words: Ward is recommended to have less than %{word_count} words

data/db/data/regions/VN.yml

@@ -13,6 +13,15 @@ week_start_day: monday
 format:
   edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{city}{zip}_{phone}"
   show: "{firstName} {lastName}_{company}_{address1}_{address2}_{city} {zip}_{country}_{phone}"
+format_extended:
+  edit: "{country}_{firstName}{lastName}_{company}_{address1}_{address2}_{neighborhood}_{city}{zip}_{phone}"
+additional_address_fields:
+  address2:
+    - key: address2
+      required: false
+    - key: neighborhood
+      decorator: ", Quận"
+      required: false
 emoji: "\U0001F1FB\U0001F1F3"
 languages:
   - fr

data/db/data/regions/_default/en.yml

@@ -63,6 +63,42 @@ en:
             unknown_for_address: Address line 1 may be incorrect.
           warnings:
             contains_too_many_words: Address line 1 is recommended to have less than %{word_count} words
+        street_name:
+          label:
+            default: Street
+            optional: Street (optional)
+          errors:
+            blank: Enter a street name
+            too_long: Street is too long (maximum is 255 characters)
+            contains_emojis: Street cannot contain emojis
+            contains_mathematical_symbols: Street cannot contain mathematical symbols
+            contains_restricted_characters: Street can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Street cannot have more than %{word_count} words
+            contains_html_tags: Street cannot contain HTML tags.
+            contains_url: Street cannot contain URLs.
+            street_unknown_for_zip: Enter a valid street name for %{zip}.
+            unknown_for_address: Street may be incorrect.
+          warnings:
+            contains_too_many_words: Street is recommended to have less than %{word_count} words
+        street_number:
+          label:
+            default: Building number
+            optional: Building number (optional)
+          errors:
+            blank: Enter a building number
+            too_long: Building number is too long (maximum is 255 characters)
+            contains_emojis: Building number cannot contain emojis
+            contains_mathematical_symbols: Building number cannot contain mathematical symbols
+            contains_restricted_characters: Building number can only contain letters,
+              numbers, local characters, and special characters
+            contains_html_tags: Building number cannot contain HTML tags.
+            contains_url: Building number cannot contain URLs.
+            building_number_invalid: Building number couldn't be located for %{street},
+              %{zip}.
+            unknown_for_address: Building number may be incorrect.
+          warnings:
+            contains_too_many_words: Building number is recommended to have less than %{word_count} words
         address2:
           label:
             default: Apartment, suite, etc.
@@ -83,9 +119,28 @@ en:
             building_number_invalid: Building number couldn't be located for %{street},
               %{zip}.
             unknown_for_address: Address line 2 may be incorrect.
-
           warnings:
             contains_too_many_words: Address line 2 is recommended to have less than %{word_count} words
+        neighborhood:
+          label:
+            default: Neighborhood
+            optional: Neighborhood (optional)
+          errors:
+            blank: Enter a neighborhood
+            too_long: Neighborhood is too long (maximum is 255 characters)
+            contains_emojis: Neighborhood cannot contain emojis
+            contains_mathematical_symbols: Neighborhood cannot contain mathematical symbols
+            contains_restricted_characters: Neighborhood can only contain letters, numbers,
+              local characters, and special characters
+            contains_too_many_words: Neighborhood cannot have more than %{word_count}
+              words
+            contains_html_tags: Neighborhood cannot contain HTML tags.
+            contains_url: Neighborhood cannot contain URLs.
+            unknown_for_city: Enter a valid neighborhood name for %{city}.
+            unknown_for_zip: Enter a valid neighborhood name for %{zip}.
+            unknown_for_address: Neighborhood may be incorrect.
+          warnings:
+            contains_too_many_words: Neighborhood is recommended to have less than %{word_count} words
         city:
           label:
             default: City

data/docs/address_format_strings.md

@@ -0,0 +1,111 @@
+# Address format strings
+
+## Introduction <!-- omit in toc -->
+
+Worldwide defines different address format strings that control the layout of address elements for each country region.
+
+Each format string has a different syntax, and is meant for use in different scenarios.
+
+This page aims to document these syntaxes, their usage and limitations for those who need to create/edit them.
+
+**⚠️ Warning:** You shouldn't parse these format strings yourself, but instead make use of the higher-level libraries that already consume these strings. This document is meant for those creating the higher-level libraries, or for those who need to make changes to these format strings.
+
+## Table of Contents <!-- omit in toc -->
+
+- [Address format strings](#address-format-strings)
+  - [`edit`](#edit)
+    - [English description](#english-description)
+    - [Grammar](#grammar)
+  - [`show`](#show)
+    - [English description](#english-description-1)
+    - [Grammar](#grammar-1)
+    - [Limitations](#limitations)
+      - [No escaping of special characters](#no-escaping-of-special-characters)
+      - [No space-less formats](#no-space-less-formats)
+      - [No free-standing prefix/suffix characters](#no-free-standing-prefixsuffix-characters)
+      - [No special concatenation characters](#no-special-concatenation-characters)
+
+## `edit`
+
+The `edit` address format string controls the layout of elements within an address input form for a country region.
+
+e.g., `{company}_{address1}_{address2}_{city}_{country}{province}{zip}_{phone}`
+
+![Example address input form formatted using the `edit` address format](images/edit.png)
+
+**⚠️ Warning:** There's a lot more to creating an address form than just the layout of the fields (error messages, optionality, placeholders, etc.) You probably shouldn't parse `edit` yourself; use a pre-existing, higher-level library instead. This document is meant for those creating the higher-level libraries.
+
+### English description
+
+1. Fields are specified by wrapping the field name in curly braces: `{field_name}`
+2. Lines of fields are separated by an underscore `_`
+
+### Grammar
+
+Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for `edit` address format strings:
+
+```
+EditFormatString ::= Lines
+Lines ::= Line (LineSeparator Lines)?
+LineSeparator ::= '_'
+Line ::= Field+
+Field ::= '{' Identifier '}'
+Identifier ::= [a-zA-Z0-9_]+
+```
+
+## `show`
+
+The `show` address format string controls how addresses should be rendered as part of a UI.
+
+e.g., `{firstName} {lastName}_{company}_{address1}_{address2}_{city} {province} {zip}_{country}_{phone}`
+
+![Example address formatted using the `show` address format](images/show.png)
+
+### English description
+
+1. Fields are specified by wrapping the field name in curly braces: `{field_name}`
+2. Lines of fields are separated by an underscore `_`
+3. Fields are separated by an space character
+4. Other characters are permitted as prefixes/suffixes of a field
+   * Note: the prefix of a field is separated from the suffix of a preceding field by the space character separating the fields
+
+### Grammar
+
+Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for `show` address format strings:
+
+```
+ShowFormatString ::= Lines
+Lines ::= Line (LineSeparator Lines)?
+LineSeparator ::= '_'
+Line ::= PrefixedSuffixedField (FieldSeparator PrefixedSuffixedField)*
+FieldSeparator ::= ' '
+PrefixedSuffixedField ::= (Prefix? Field Suffix?)
+Field ::= '{' Identifier '}'
+Identifier ::= [a-zA-Z0-9_]+
+Prefix ::= Text
+Suffix ::= Text
+Text ::= [^_{} ]+
+```
+
+### Limitations
+
+There are a number of limitations to the `show` syntax that cannot cover the complexity of the world's address formatting.
+
+#### No escaping of special characters
+
+There is no support for escaping special characters: `{`, `}`, `_`, `<space>`
+
+#### No space-less formats
+
+Since the fields are space-separated, there is no way to specify a non-separator space character.
+However, many languages (e.g., English) are space-delimited, so libraries using the `show` string end up concatenatiing the fields together using spaces, even if the language doesn't require spaces (e.g., Japanese).
+
+#### No free-standing prefix/suffix characters
+
+There is no way to specify prefix/suffix characters that will be included regardless of the provided values.
+Any characters besides a field name are either prefixes or suffixes of a field, and therefore if a value for the field is not provided, the associated prefix/suffix characters are also not provided.
+
+#### No special concatenation characters
+
+There is no way to specify characters other than space characters for concatenating two fields.
+For example, in Brazil, when the `city` and `province` fields are formatted adjacent to one another, instead of a space between the fields, ` - ` should be used. These concatenation characters are neither a prefix nor a suffix of either field, so cannot be specified in this format's syntax.

data/lib/worldwide/field.rb

@@ -11,7 +11,10 @@ module Worldwide
       :last_name,
       :company,
       :address1,
+      :street_name,
+      :street_number,
       :address2,
+      :neighborhood,
       :city,
       :province,
       :zip,

data/lib/worldwide/region.rb

@@ -19,6 +19,7 @@ module Worldwide
       :example_city,
       :flag,
       :format,
+      :format_extended,
       :group,
       :group_name,
       :cldr_code,
@@ -32,6 +33,7 @@ module Worldwide
       :zip_example,
       :zip_regex,
       :zip_requirement,
+      :additional_address_fields,
     ]
 
     # A region may have more than one parent.
@@ -73,9 +75,15 @@ module Worldwide
     #   - show: how to arrange the fields when formatting an address for display
     attr_accessor :format
 
+    # Hash of strings denoting how to format an address in this region, including substitute and/or additional fields.
+    # The format is described in https://shopify.engineering/handling-addresses-from-all-around-the-world
+    #   - edit: the fields to present on an address input form
+    #   - show: how to arrange the fields when formatting an address for display
+    attr_accessor :format_extended
+
     # The string that results from appending " Countries" to the adjectival form of the {group_name}
     # @example
-    #   CountryDb.country(code: "CA").group == "North American Countries"
+    #   Worldwide.region(code: "CA").group == "North American Countries"
     attr_accessor :group
 
     # The continent that this region is part of.
@@ -101,13 +109,11 @@ module Worldwide
     # The code used by the legacy Shopify ecosystem for this region.
     # E.g., for MX-CMX it will return "DF".
     # This code should _never_ be shown in the user interface.
-    # This is the code that was traditionally returned by "country_db".
     attr_reader :legacy_code
 
     # The name used by the legacy Shopify ecosystem for this region.
     # E.g., "Sao Tome And[sic] Principe" for "ST".
     # This name should _never_ be shown in the user interface.
-    # This name is the name that was traditionally returned by "country_db".
     attr_reader :legacy_name
 
     # Other names that may be used to refer to this region.
@@ -191,6 +197,9 @@ module Worldwide
     # If true, then the province is optional for addresses in this region.
     attr_accessor :province_optional
 
+    # A hash of additional address fields and the rules for concatening them into the standard fields
+    attr_accessor :additional_address_fields
+
     def initialize(
       alpha_three: nil,
       continent: false,
@@ -226,11 +235,13 @@ module Worldwide
       @tax_rate = tax_rate
       @use_zone_code_as_short_name = use_zone_code_as_short_name
 
+      @additional_address_fields = {}
       @building_number_required = false
       @building_number_may_be_in_address2 = false
       @currency = nil
       @flag = nil
       @format = {}
+      @format_extended = {}
       @group = nil
       @group_name = nil
       @languages = []

data/lib/worldwide/regions_loader.rb

@@ -95,6 +95,7 @@ module Worldwide
     end
 
     def apply_territory_attributes(region, spec)
+      region.additional_address_fields = spec["additional_address_fields"] || {}
       region.building_number_required = spec["building_number_required"] || false
       region.building_number_may_be_in_address2 = spec["building_number_may_be_in_address2"] || false
       currency_code = spec["currency"]
@@ -102,6 +103,7 @@ module Worldwide
       region.currency = Worldwide.currency(code: currency_code) unless currency_code.nil?
       region.flag = spec["emoji"]
       region.format = spec["format"]
+      region.format_extended = spec["format_extended"] || {}
       region.group = spec["group"]
       region.group_name = spec["group_name"]
       region.hide_provinces_from_addresses = spec["hide_provinces_from_addresses"] || false

data/lib/worldwide/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Worldwide
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/worldwide/zip.rb

@@ -85,7 +85,7 @@ module Worldwide
     def normalize(country_code:, zip:, allow_autofill: true, strip_extraneous_characters: false)
       input = zip # preserve the original zip, in case we need to fall back to it
 
-      return input if country_code.nil?
+      return input if Util.blank?(country_code)
 
       country = Worldwide.region(code: country_code)
       return zip if country.nil? || NORMALIZATION_DISABLED_COUNTRIES.include?(country.iso_code)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: worldwide
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Shopify
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-04-11 00:00:00.000000000 Z
+date: 2024-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -6552,6 +6552,7 @@ files:
 - db/data/regions/CI.yml
 - db/data/regions/CK.yml
 - db/data/regions/CL.yml
+- db/data/regions/CL/en.yml
 - db/data/regions/CM.yml
 - db/data/regions/CN.yml
 - db/data/regions/CN/bg-BG.yml
@@ -7947,9 +7948,11 @@ files:
 - db/data/regions/TN.yml
 - db/data/regions/TO.yml
 - db/data/regions/TR.yml
+- db/data/regions/TR/en.yml
 - db/data/regions/TT.yml
 - db/data/regions/TV.yml
 - db/data/regions/TW.yml
+- db/data/regions/TW/en.yml
 - db/data/regions/TZ.yml
 - db/data/regions/UA.yml
 - db/data/regions/UG.yml
@@ -8061,6 +8064,7 @@ files:
 - db/data/regions/VE.yml
 - db/data/regions/VG.yml
 - db/data/regions/VN.yml
+- db/data/regions/VN/en.yml
 - db/data/regions/VU.yml
 - db/data/regions/WF.yml
 - db/data/regions/WS.yml
@@ -8171,6 +8175,9 @@ files:
 - db/data/regions/_default/zh-TW.yml
 - db/data/world.yml
 - db/extant_outcodes.yml
+- docs/address_format_strings.md
+- docs/images/edit.png
+- docs/images/show.png
 - formats.md
 - lib/worldwide.rb
 - lib/worldwide/address.rb
@@ -8233,7 +8240,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.7
+rubygems_version: 3.5.10
 signing_key: 
 specification_version: 4
 summary: Internationalization and localization APIs