holidays · ppeble · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026 · Apr 22, 2026
diff --git a/Gemfile b/Gemfile
@@ -1,6 +1,7 @@
 source 'https://rubygems.org'
 
 gem 'rspec', '~> 3'
+gem 'countries'
 gem 'pry', :require => false
 gem 'spoon', :require => false
 gem 'simplecov', :require => false
diff --git a/ar.yaml b/ar.yaml
@@ -8,6 +8,8 @@
 # - https://www.argentina.gob.ar/interior/feriados-nacionales-2020
 # - https://www.argentina.gob.ar/interior/feriados-nacionales-2021
 ---
+region_names:
+  ar: "Argentina"
 methods:
   to_nearest_monday:
     arguments: date

diff --git a/at.yaml b/at.yaml
@@ -6,6 +6,8 @@
 # - http://www.timeanddate.com/calendar/index.html?country=8
 # - http://www.germany.info/relaunch/welcome/travel/holidays.html
 ---
+region_names:
+  at: "Austria"
 months:
   0:
   - name: Ostermontag

diff --git a/au.yaml b/au.yaml
@@ -6,6 +6,21 @@
 # - http://www.wst.tas.gov.au/employment_info/public_holidays
 # - https://www.fairwork.gov.au/leave/public-holidays/list-of-public-holidays
 ---
+region_names:
+  au: "Australia"
+  au_act: "Australian Capital Territory"
+  au_nsw: "New South Wales"
+  au_nt: "Northern Territory"
+  au_qld: "Queensland"
+  au_qld_brisbane: "Brisbane"
+  au_qld_cairns: "Cairns"
+  au_sa: "South Australia"
+  au_tas: "Tasmania"
+  au_tas_north: "Northern Tasmania"
+  au_tas_south: "Southern Tasmania"
+  au_vic: "Victoria"
+  au_vic_melbourne: "Melbourne"
+  au_wa: "Western Australia"
 months:
   0:
   - name: Good Friday

diff --git a/be_fr.yaml b/be_fr.yaml
@@ -4,6 +4,8 @@
 # Sources:
 # - http://en.wikipedia.org/wiki/Public_holidays_in_Belgium
 ---
+region_names:
+  be_fr: "Belgium (French)"
 months:
   0:
   - name: Pâques

diff --git a/be_nl.yaml b/be_nl.yaml
@@ -4,6 +4,8 @@
 # Sources:
 # - http://en.wikipedia.org/wiki/Public_holidays_in_Belgium
 ---
+region_names:
+  be_nl: "Belgium (Dutch)"
 months:
   0:
   - name: Pasen

diff --git a/bg.yaml b/bg.yaml
@@ -3,6 +3,9 @@
 # Updated: 2015-04-01.
 # Source:  http://en.wikipedia.org/wiki/Public_holidays_in_Bulgaria
 ---
+region_names:
+  bg_bg: "Bulgaria"
+  bg_en: "Bulgaria"
 months:
   0:
   - name: Good Friday

diff --git a/br.yaml b/br.yaml
@@ -6,6 +6,8 @@
 # - http://pt.wikipedia.org/wiki/Feriados_no_Brasil
 
 ---
+region_names:
+  br: "Brazil"
 months:
   0:
   - name: Carnaval # same as Shrove Tuesday

diff --git a/ca.yaml b/ca.yaml
@@ -8,6 +8,21 @@
 #  - 'Nunavut’s legislative assembly voted to pass Bill 29 making Nunavut Day', July 9, an officially statutory holiday across the territory. https://www.gov.nu.ca/human-resources/information/public-service-holidays
 #  - 'According to Manitoba labour standards, Terry Fox Day is not a formal holiday. https://www.gov.mb.ca/labour/standards/doc,gen-holidays-after-april-30-07,factsheet.html#q13'
 ---
+region_names:
+  ca: "Canada"
+  ca_ab: "Alberta"
+  ca_bc: "British Columbia"
+  ca_mb: "Manitoba"
+  ca_nb: "New Brunswick"
+  ca_nl: "Newfoundland and Labrador"
+  ca_ns: "Nova Scotia"
+  ca_nt: "Northwest Territories"
+  ca_nu: "Nunavut"
+  ca_on: "Ontario"
+  ca_pe: "Prince Edward Island"
+  ca_qc: "Quebec"
+  ca_sk: "Saskatchewan"
+  ca_yt: "Yukon"
 months:
   0:
   - name: Good Friday

diff --git a/ch.yaml b/ch.yaml
@@ -25,6 +25,34 @@
 #          - 26th of December is not celebrated in case the 25th is a Monday or a Friday.
 # * ch_ne: 26th of December and 2nd of January are only celebrated in case 25th of December and 1st of January are Sundays
 ---
+region_names:
+  ch: "Switzerland"
+  ch_ag: "Aargau"
+  ch_ai: "Appenzell Innerrhoden"
+  ch_ar: "Appenzell Ausserrhoden"
+  ch_be: "Bern"
+  ch_bl: "Basel-Landschaft"
+  ch_bs: "Basel-Stadt"
+  ch_fr: "Fribourg"
+  ch_ge: "Genève"
+  ch_gl: "Glarus"
+  ch_gr: "Graubünden"
+  ch_ju: "Jura"
+  ch_lu: "Luzern"
+  ch_ne: "Neuchâtel"
+  ch_nw: "Nidwalden"
+  ch_ow: "Obwalden"
+  ch_sg: "Sankt Gallen"
+  ch_sh: "Schaffhausen"
+  ch_so: "Solothurn"
+  ch_sz: "Schwyz"
+  ch_tg: "Thurgau"
+  ch_ti: "Ticino"
+  ch_ur: "Uri"
+  ch_vd: "Vaud"
+  ch_vs: "Valais"
+  ch_zg: "Zug"
+  ch_zh: "Zürich"
 months:
   0:
   - name: Karfreitag

diff --git a/cl.yaml b/cl.yaml
@@ -7,6 +7,8 @@
 # - http://www.feriadoschilenos.cl
 #
 ---
+region_names:
+  cl: "Chile"
 months:
   0:
   - name: Viernes Santo

diff --git a/co.yaml b/co.yaml
@@ -10,6 +10,8 @@
 # - https://www.timeanddate.com/holidays/colombia/
 # - http://www.bank-holidays.com/country/Colombia_42.htm
 ---
+region_names:
+  co: "Colombia"
 methods:
   # Movable holiday: when they do not fall on a Monday, these holidays are observed the following Monday.
   to_following_monday_if_not_monday:

diff --git a/cr.yaml b/cr.yaml
@@ -6,6 +6,9 @@
 # Sources:
 # - http://en.wikipedia.org/wiki/Public_holidays_in_Costa_Rica
 #
+---
+region_names:
+  cr: "Costa Rica"
 months:
   0:
   - name: Jueves Santo

diff --git a/cy.yaml b/cy.yaml
@@ -5,6 +5,8 @@
     # https://el.wikipedia.org/wiki/%CE%94%CE%B7%CE%BC%CF%8C%CF%83%CE%B9%CE%B5%CF%82_%CE%B1%CF%81%CE%B3%CE%AF%CE%B5%CF%82_%CF%83%CF%84%CE%B7%CE%BD_%CE%9A%CF%8D%CF%80%CF%81%CE%BF
     # https://www.centralbank.cy/the-bank/working-hours-bank-holidays
 ---
+region_names:
+  cy: "Cyprus"
 months:
   0:
   - name: Μεγάλη Παρασκευή

diff --git a/cz.yaml b/cz.yaml
@@ -5,6 +5,8 @@
 # - http://cs.wikipedia.org/wiki/%C4%8Cesk%C3%BD_st%C3%A1tn%C3%AD_sv%C3%A1tek
 # - http://www.mpsv.cz/cs/74
 ---
+region_names:
+  cz: "Czechia"
 months:
   0:
   - name: Velký pátek

diff --git a/de.yaml b/de.yaml
@@ -40,6 +40,28 @@
 # - https://www.statistik.bayern.de/statistik/bevoelkerungsstand/00141.php
 # - http://www.thueringen.de/mam/th3/tim/verwaltungsrecht/fronleichnam_gemeindeschluesselzahlen.pdf
 ---
+region_names:
+  de: "Germany"
+  de_bb: "Brandenburg"
+  de_be: "Berlin"
+  de_bw: "Baden-Württemberg"
+  de_by: "Bayern"
+  de_by_augsburg: "Augsburg (Bayern)"
+  de_by_cath: "Bayern (Catholic regions)"
+  de_hb: "Bremen"
+  de_he: "Hessen"
+  de_hh: "Hamburg"
+  de_mv: "Mecklenburg-Vorpommern"
+  de_ni: "Niedersachsen"
+  de_nw: "Nordrhein-Westfalen"
+  de_rp: "Rheinland-Pfalz"
+  de_sh: "Schleswig-Holstein"
+  de_sl: "Saarland"
+  de_sn: "Sachsen"
+  de_sn_sorbian: "Sachsen (Sorbian regions)"
+  de_st: "Sachsen-Anhalt"
+  de_th: "Thüringen"
+  de_th_cath: "Thüringen (Catholic regions)"
 months:
   0:
   - name: Karfreitag

diff --git a/dk.yaml b/dk.yaml
@@ -6,6 +6,8 @@
 # - http://www.amblondon.um.dk/en/menu/AboutDenmark/PublicHolidaysInDK/PublicHolidaysinDenmark-until2010.htm
 # - http://borger.dk/forside/kirke-og-tro/folkekirken/officielle-helligdage
 ---
+region_names:
+  dk: "Denmark"
 months:
   0:
   - name: Fastelavn

diff --git a/doc/SYNTAX.md b/doc/SYNTAX.md
@@ -1,12 +1,13 @@
 # Holiday Definition Syntax
 
-The definition syntax is a custom format developed over the life of this project. All holidays are defined in these YAML files. These definition files have three main top-level properties:
+The definition syntax is a custom format developed over the life of this project. All holidays are defined in these YAML files. These definition files have four top-level properties:
 
+* `region_names` - human-readable English names for each region defined in this file
 * `months` - this is the meat! All definitions for months 1-12 are defined here
 * `methods` - this contains any custom logic that your definitions require
 * `tests` - this contains the tests for your definitions
 
-The `months` property is required. The two other properties are not strictly required but are almost always used.
+The `months` property is required. The remaining properties are not strictly required but are almost always used.
 
 In fact, if you leave out `tests` your PR will probably not be accepted unless there is a very, very good reason for leaving it out.
 
@@ -47,6 +48,35 @@ We recognize that these definitions can be highly subjective. If you disagree wi
 
 There are certain holidays that can be legally observed on different days than they occur. For example, if a holiday falls on a Saturday but it is legally observed on the following Monday then you can define it as `observed` on the Monday. Please see the section below for more details and examples.
 
+## Region Names
+
+Each definition file should include a `region_names` section mapping every region symbol used in that file to its English name. Names use the common English name from [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166) wherever a standard exists. Using the ISO standard as the source of truth means that i18n libraries can translate these names into other languages without requiring this project to maintain its own translations.
+
+```yaml
+region_names:
+  gb: "United Kingdom"
+  gb_eng: "England"
+  gb_wls: "Wales"
+  gb_sct: "Scotland"
+  gb_nir: "Northern Ireland"
+```
+
+### Naming conventions
+
+- **ISO 3166-1 countries** (e.g. `:gb`, `:fr`): use the ISO 3166-1 common English name (e.g. `gb` is `"United Kingdom"`, not `"United Kingdom of Great Britain and Northern Ireland"`)
+- **ISO 3166-2 subdivisions** (e.g. `:gb_eng`, `:de_by`): use the ISO 3166-2 official name, note that ISO 3166-2 names are in the official language of the country, not necessarily English (e.g. `de_by` is `"Bayern"`, not `"Bavaria"`)
+- **Non-geographic regions** (e.g. `:nyse`, `:federalreserve`): use a clear English descriptive name
+- **Gem-specific composite regions** with no ISO counterpart (e.g. `:gb_eaw`): use a reasonable English descriptive name
+
+### YAML quoting note
+
+Region symbols that are YAML reserved words must be quoted. For example, `no` (Norway) is interpreted as a boolean by YAML parsers and must be written as `"no"`:
+
+```yaml
+region_names:
+  "no": "Norway"
+```
+
 ## Months
 
 Holidays are grouped by month from 1 through 12.  Each entry within a month can have several properties depending on the behavior of the holiday. Each section below lays out the various different ways you can define your holiday.