Add localization support

.gitignore

@@ -1,16 +1,20 @@
-build/
+build/*
 dist/
 venv/
 MANIFEST
 .coverage
 *.egg-info
+*.mo
+*.pot
 *.pyc
 *.DS_Store
 coverage.xml
 .tox
 .venv
 docs/_build
+docs/build
 docs/source/_build
+holidays/locale/pot
 
 # IDE Stuff
 .idea

.pre-commit-config.yaml

@@ -15,6 +15,7 @@ repos:
     rev: 23.1.0
     hooks:
       - id: black
+        exclude: ^(docs|scripts/l10n/msgfmt.py)
         language_version: python3
 
   - repo: https://github.com/pycqa/flake8
@@ -24,6 +25,7 @@ repos:
         additional_dependencies:
           - flake8-print
         args: [--max-line-length=79]
+        exclude: ^(docs|scripts/l10n/msgfmt.py)
 
   - repo: https://github.com/pre-commit/mirrors-isort
     rev: v5.10.1
@@ -32,7 +34,7 @@ repos:
         # holidays/countries/__init__.py is excluded due to a bug whereby
         # black and isort don't agree and enter into an infinite fix loop.
         # TODO remove this exclusion when isort and black play nice again.
-        exclude: ^docs/|^holidays/countries/__init__.py
+        exclude: ^(docs|holidays/countries/__init__.py|scripts/l10n/msgfmt.py)
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.0.0

CONTRIBUTING.rst

@@ -59,23 +59,60 @@ You can specific tests using ``pytest`` command:
 
 .. code-block:: shell
 
-    $ pytest tests/countries/test_albania.py
+    $ pytest tests/countries/test_argentina.py
 
 Or even more granular:
 
 .. code-block:: shell
 
-    $ pytest tests/countries/test_albania.py::TestAlbania::test_country_aliases
+    $ pytest tests/countries/test_argentina.py::TestArgentina::test_country_aliases
 
 Due to how pytest-xdist is implemented, the -s/--capture=no option
 `doesn't work <https://pytest-xdist.readthedocs.io/en/latest/known-limitations.html#output-stdout-and-stderr-from-workers>`_.
 Use pytest directly if you need ``-s`` option:
 
 .. code-block:: shell
 
-    $ pytest -s tests/countries/test_albania.py
+    $ pytest -s tests/countries/test_argentina.py
 
 
+Localization
+--------------------------
+.. _ISO 639-1 codes: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+
+In order to add or update existing holiday names translation you'll need to
+generate pygettext .pot file first:
+
+.. code-block:: shell
+
+    $ make l10n
+
+If the template file is empty make sure that the country/market entity has the
+:py:attr:`default_language` attribute set and all holiday names are wrapped
+with ``tr``/``self.tr`` helpers. Use `ISO 639-1 codes`_ when adding new
+languages. Copy the generated template to all locale folders you're going to
+translate this country holiday names into (e.g., for Argentina:
+holidays/locale/en/LC_MESSAGES/AR.po - note the file extension difference here).
+Also copy the template to a default country language folder (e.g., for Argentina
+holidays/locale/es/LC_MESSAGES) and leave it as is. After copying the .po files
+open them with your favorite .po file editor and translate accordingly. Don't
+forget to fill in the translation file headers. Finally, update the list of
+supported translations for the country in the README.rst.
+
+If the translation already exists you'll just need to update it with the new
+template entries (your .po file editor may help you to do that with no hassle).
+
+Please also add tests (see already translated countries tests for examples).
+The .mo files are generated automatically for the tests and the python-holidays
+package so you shouldn't worry about it. Just don't forget to
+initialize the ``setUpClass`` properly:
+
+.. code-block:: python
+
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass(Argentina)
+
 Build sphinx documentation
 --------------------------
 

MANIFEST.in

@@ -1,5 +1,9 @@
+exclude tests/*
 include *.py
 include *.rst
-include LICENSE
 include CHANGES
-include py.typed
+include holidays/locale/*/LC_MESSAGES/*.mo
+include holidays/locale/*/LC_MESSAGES/*.po
+include holidays/py.typed
+include LICENSE
+include scripts/l10n/msgfmt.py

Makefile

@@ -4,6 +4,7 @@ help:
 	@echo "    coverage      identify code not covered with tests"
 	@echo "    help          show summary of available commands"
 	@echo "    install       install and setup development environment"
+	@echo "    l10n          update .pot and .po files"
 	@echo "    pre-commit    run pre-commit against all files"
 	@echo "    test          run tests (in parallel)"
 	@echo "    tox           run tox (in parallel)"
@@ -21,6 +22,10 @@ install:
 	pip install --requirement requirements/docs.txt
 	pre-commit install --hook-type pre-commit
 	pre-commit install --hook-type pre-push
+	mkdir -p holidays/locale/pot
+
+l10n:
+	scripts/l10n/generate_po_files.py
 
 pre-commit:
 	pre-commit run --all-files

README.rst

@@ -507,6 +507,42 @@ following financial markets are available:
      - NYSE market holidays (used by all other US-exchanges, including NASDAQ, etc.)
 
 
+Internationalization
+===========================
+
+.. _ISO 639-1 code: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
+
+Some of the available countries support more than one
+language for holiday names output. The default language is defined by
+:py:attr:`default_language` of :py:class:`HolidayBase` and is used as a fallback
+when neither user specified language nor user locale language available. The
+default language code is a `ISO 639-1 code`_.
+
+.. list-table::
+   :widths: 23 4 83
+   :header-rows: 1
+   :class: tight-table
+
+   * - Country
+     - Default Language
+     - Supported languages
+   * - Argentina
+     - es
+     - en, es
+   * - Canada
+     - en
+     - en, fr
+   * - Denmark
+     - da
+     - da, en
+   * - Poland
+     - pl
+     - en, pl
+   * - Ukraine
+     - uk
+     - en, uk
+
+
 Beta Version
 ------------
 

holidays/countries/argentina.py

@@ -29,6 +29,7 @@ class Argentina(HolidayBase):
     """
 
     country = "AR"
+    default_language = "es"
 
     def _populate(self, year):
         super()._populate(year)
@@ -37,18 +38,17 @@ def _populate(self, year):
         if not self.observed and self._is_weekend(year, JAN, 1):
             pass
         else:
-            self[date(year, JAN, 1)] = "Año Nuevo [New Year's Day]"
+            self[date(year, JAN, 1)] = self.tr("Año Nuevo")
 
         easter_date = easter(year)
         # Carnival days
-        name = "Día de Carnaval [Carnival's Day]"
+        name = self.tr("Día de Carnaval")
         self[easter_date + td(days=-48)] = name
         self[easter_date + td(days=-47)] = name
 
         # Memory's National Day for the Truth and Justice
-        name = (
-            "Día Nacional de la Memoria por la Verdad y la Justicia "
-            "[Memory's National Day for the Truth and Justice]"
+        name = self.tr(
+            "Día Nacional de la Memoria por la Verdad y la Justicia"
         )
 
         if not self.observed and self._is_weekend(year, MAR, 24):
@@ -57,9 +57,9 @@ def _populate(self, year):
             self[date(year, MAR, 24)] = name
 
         # Holy Week
-        name_thu = "Semana Santa (Jueves Santo) [Holy day (Holy Thursday)]"
-        name_fri = "Semana Santa (Viernes Santo) [Holy day (Holy Friday)]"
-        name_easter = "Día de Pascuas [Easter Day]"
+        name_thu = self.tr("Semana Santa (Jueves Santo)")
+        name_fri = self.tr("Semana Santa (Viernes Santo)")
+        name_easter = self.tr("Día de Pascuas")
 
         self[easter_date + td(days=-3)] = name_thu
         self[easter_date + td(days=-2)] = name_fri
@@ -73,61 +73,52 @@ def _populate(self, year):
         if not self.observed and self._is_weekend(year, APR, 2):
             pass
         else:
-            self[date(year, APR, 2)] = (
-                "Día del Veterano y de los Caidos "
-                "en la Guerra de Malvinas [Veterans"
-                " Day and the Fallen in the"
-                " Malvinas War]"
+            self[date(year, APR, 2)] = self.tr(
+                "Día del Veterano y de los Caidos en la Guerra de Malvinas"
             )
 
         # Labor Day
-        name = "Día del Trabajo [Labour Day]"
+        name = self.tr("Día del Trabajo")
         if not self.observed and self._is_weekend(year, MAY, 1):
             pass
         else:
             self[date(year, MAY, 1)] = name
 
         # May Revolution Day
-        name = "Día de la Revolucion de Mayo [May Revolution Day]"
+        name = self.tr("Día de la Revolución de Mayo")
         if not self.observed and self._is_weekend(year, MAY, 25):
             pass
         else:
             self[date(year, MAY, 25)] = name
 
         # Day Pass to the Immortality of General Martín Miguel de Güemes.
-        name = (
-            "Día Pase a la Inmortalidad "
-            "del General Martín Miguel de Güemes [Day Pass "
-            "to the Immortality of General Martín Miguel de Güemes]"
+        name = self.tr(
+            "Día Pase a la Inmortalidad del General Martín Miguel de Güemes"
         )
         if not self.observed and self._is_weekend(year, JUN, 17):
             pass
         else:
             self[date(year, JUN, 17)] = name
 
         # Day Pass to the Immortality of General D. Manuel Belgrano.
-        name = (
-            "Día Pase a la Inmortalidad "
-            "del General D. Manuel Belgrano [Day Pass "
-            "to the Immortality of General D. Manuel Belgrano]"
+        name = self.tr(
+            "Día Pase a la Inmortalidad del General D. Manuel Belgrano"
         )
         if not self.observed and self._is_weekend(year, JUN, 20):
             pass
         else:
             self[date(year, JUN, 20)] = name
 
         # Independence Day
-        name = "Día de la Independencia [Independence Day]"
+        name = self.tr("Día de la Independencia")
         if not self.observed and self._is_weekend(year, JUL, 9):
             pass
         else:
             self[date(year, JUL, 9)] = name
 
         # Day Pass to the Immortality of General D. José de San Martin
-        name = (
-            "Día Pase a la Inmortalidad "
-            "del General D. José de San Martin [Day Pass "
-            "to the Immortality of General D. José de San Martin]"
+        name = self.tr(
+            "Día Pase a la Inmortalidad del General D. José de San Martin"
         )
         if not self.observed and self._is_weekend(year, AUG, 17):
             pass
@@ -138,15 +129,13 @@ def _populate(self, year):
         if not self.observed and self._is_weekend(year, OCT, 12):
             pass
         elif year < 2010:
-            self[date(year, OCT, 12)] = "Día de la Raza [Columbus day]"
+            self[date(year, OCT, 12)] = self.tr("Día de la Raza")
         else:
-            self[date(year, OCT, 12)] = (
-                "Día del Respeto a la Diversidad"
-                " Cultural [Respect for"
-                " Cultural Diversity Day]"
+            self[date(year, OCT, 12)] = self.tr(
+                "Día del Respeto a la Diversidad Cultural"
             )
         # National Sovereignty Day
-        name = "Día Nacional de la Soberanía [National Sovereignty Day]"
+        name = self.tr("Día Nacional de la Soberanía")
         if not self.observed and self._is_weekend(year, NOV, 20):
             pass
         elif year >= 2010:
@@ -156,12 +145,10 @@ def _populate(self, year):
         if not self.observed and self._is_weekend(year, DEC, 8):
             pass
         else:
-            self[
-                date(year, DEC, 8)
-            ] = "La Inmaculada Concepción [Immaculate Conception]"
+            self[date(year, DEC, 8)] = self.tr("La Inmaculada Concepción")
 
         # Christmas
-        self[date(year, DEC, 25)] = "Navidad [Christmas]"
+        self[date(year, DEC, 25)] = self.tr("Navidad")
 
 
 class AR(Argentina):