{"id":28430979,"url":"https://github.com/elixir-cldr/cldr_calendars_lunisolar","last_synced_at":"2025-09-04T12:50:55.988Z","repository":{"id":43332281,"uuid":"400944846","full_name":"elixir-cldr/cldr_calendars_lunisolar","owner":"elixir-cldr","description":"Chinese localised calendar for Elixir and CLDR","archived":false,"fork":false,"pushed_at":"2025-03-19T00:33:50.000Z","size":953,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-05T14:39:42.138Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elixir-cldr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-29T03:53:16.000Z","updated_at":"2025-03-19T00:31:11.000Z","dependencies_parsed_at":"2024-06-21T17:24:59.074Z","dependency_job_id":"9b601781-363c-486a-9ec0-573accfc90e3","html_url":"https://github.com/elixir-cldr/cldr_calendars_lunisolar","commit_stats":{"total_commits":37,"total_committers":2,"mean_commits":18.5,"dds":"0.027027027027026973","last_synced_commit":"edd441a5ade2e828ef3a9bff7856341e07a0445c"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/elixir-cldr/cldr_calendars_lunisolar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-cldr%2Fcldr_calendars_lunisolar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-cldr%2Fcldr_calendars_lunisolar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-cldr%2Fcldr_calendars_lunisolar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-cldr%2Fcldr_calendars_lunisolar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elixir-cldr","download_url":"https://codeload.github.com/elixir-cldr/cldr_calendars_lunisolar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elixir-cldr%2Fcldr_calendars_lunisolar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263588081,"owners_count":23484860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-05T14:30:42.626Z","updated_at":"2025-07-04T17:31:32.810Z","avatar_url":"https://github.com/elixir-cldr.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lunisolar Calendars\n\nThis library implements the Chinese, Japanese and Korean lunisolar calendars. Lunisolar calendars use the lunar cycle to define months but the solar cycle to define years. In reconciling these two cycles, occasionally one of the lunar months is extended to bring the cycles into alignment. Since the number of months in a year does not change (they are always numbered 1 to 12), the extended month is called a \"leap month\".\n\nThe traditional Chinese, Japanese and Korean calendars all use the same astronomical principles with the only difference being the reference point from which the observations are made and the preferred epoch date. Today, the Chinese calendar uses Beijing as the reference, the Japanese calendar uses Tokyo and the Korean calendar uses Seoul.\n\n## Installation\n\nThe minimum supported Elixir version is 1.12.\n\nThe package can be installed by adding `ex_cldr_calendars_lunisolar` and `tz_world` to the list of dependencies in `mix.exs`.  Additionally, add either `tzdata` or `tz` as a time zone database.\n\n```elixir\ndef deps do\n  [\n    {:ex_cldr_calendars_lunisolar, \"~\u003e 1.0\"},\n\n    # Provides time zone lookup for astro\n    # the is a transitive dependency that converts locations\n    # time zones.\n    {:tz_world, \"~\u003e 1.3\"},\n\n    # Choose tz or tzdata as time zone databases.\n    {:tz, \"~\u003e 0.26\"}\n  ]\nend\n```\nDocumentation can be found at [https://hexdocs.pm/ex_cldr_calendars_lunisolar](https://hexdocs.pm/ex_cldr_calendars_lunisolar).\n\n### Install the time zone geo data\n\nIn order to map a location to a time zone, the dependency `tz_world` needs a time zone geography data set to be donwloaded. This is done once with the following `mix` task:\n\n```elixir\nmix tz_world.update\n```\n\n## Usage\n\n[ex_cldr_calendars_lunisolar](https://hex.pm/packages/ex_cldr_calenars_lunisolar) conforms to both the `Calendar` and `Cldr.Calendar` behaviours and therefore the functions in the `Date`, `DateTime`, `NaiveDateTime`, `Time` and `Calendar` functions are supported.\n\nFor Elixir version 1.12 and later `Sigil_D` supports user-defined calendars:\n```elixir\niex\u003e ~D[4660-03-30 Cldr.Calendar.Chinese]\n~D[4660-03-30 Cldr.Calendar.Chinese]\n```\n\n## Lunisolar Date representation\n\nLunisolar calendars have a leap year when the lunar cycle falls too far out of alignment with the solar year. In those years, like Gregorian 2023, a leap month is inserted into the calendar. In 2023, the leap month is month 2 so the sequence of months goes \"month 1\" -\u003e \"month 2\" -\u003e \"leap month 2\" -\u003e \"month 3\". The Elixir date structures can't accomodate this kind of annotation so the lunisolar calendar implementations in the library adopt a different approach. The month in the date struct is an *ordinal* month (ie considered the nth month) not the *cardinal* month as in other calendars. To create dates using the traditional lunisolar month notation see the next section.\n\nThis means that the month numbers in a lunisolar leap year are:\n\n| Calendar month | Date struct month | Example for Gregorian 2023 (Korean calendar 4356) using Date.to_string/2 in :ko locale |\n| :------------: | :---------------: | :------------------------------------------------------------------------------------- |\n| 1              | 1                 | \"4356. 1. 1.\"                                                                          |\n| 2              | 2                 | \"4356. 2. 1.\"                                                                          |\n| leap 2         | 3                 | \"4356. 윤2. 1.\"                                                                        |\n| 3              | 4                 | \"4356. 3. 1.\"                                                                          |\n| 4              | 5                 | \"4356. 4. 1.\"                                                                          |\n\n## Dates with lunar months\n\nKey events in China, Japan, Korea and other territories are defined by their lunar dates. Lunar new year is `01-01` (month-year), Buddha's birthday is celebrated on `04-08` and the Korean thanksgiving day is `08-15`. Note that these month numbers *do not* map directly to the date struct's ordinal month numbers. To facilitate creating dates in the traditional notation, the functions `Cldr.Calendar.Chinese.new/3`, `Cldr.Calendar.LunarJapanese.new/3` and `Cldr.Calendar.Korean.new/3` are provided. The notation `{lunar_month, :leap}` is used to denote the leap month in a leap year.\n\n```elixir\n# New Years day\niex\u003e Cldr.Calendar.Chinese.new(4660, 1, 1)\n{:ok, ~D[4660-01-01 Cldr.Calendar.Chinese]}\n\n#Buddha's birthday\niex\u003e Cldr.Calendar.LunarJapanese.new(1379, 4, 8)\n{:ok, ~D[1379-05-08 Cldr.Calendar.LunarJapanese]}\n\n# Korean thanksgiving day\niex\u003e Cldr.Calendar.Korean.new(4356, 8, 15)\n{:ok, ~D[4356-09-15 Cldr.Calendar.Korean]}\n\n# A day in the leap month\niex\u003e Cldr.Calendar.Chinese.new(4660, {3, :leap}, 1)\n{:ok, ~D[4660-04-01 Cldr.Calendar.Chinese]}\niex\u003e Cldr.Calendar.Chinese.new(4660, {4, :leap}, 1)\n{:error, :invalid_date}\n```\n\n## Localization\n\n`ex_cldr_calendars_lunisolar` depends on [ex_cldr_calendars](https://hex.pm/packages/ex_cldr_calendars) which supports calendar localization. For full date and time formatting see [ex_cldr_dates_times](https://hex.pm/packages/ex_cldr_dates_times).\n\nBasic localization is executed by the `Cldr.Calendar.localize/3`. For example:\n\n```elixir\n# Months are ordinal numbers so in Gregorian 2023, Korean 4356\n# the ordinal month 3 is the Korean leap month 2\niex\u003e Cldr.Calendar.localize(~D[4356-03-01 Cldr.Calendar.Korean], :month, locale: :ko)\n\"윤2월\"\n\n# Since there is a leap month prior to ordinal month 4\n# the month number localizes to 3\niex\u003e Cldr.Calendar.localize(~D[4356-04-01 Cldr.Calendar.Korean], :month, locale: :ko)\n\"3월\"\n\niex\u003e Cldr.Calendar.localize(~D[4660-04-01 Cldr.Calendar.Chinese], :day_of_week)\n\"Thu\"\n\niex\u003e Cldr.Calendar.localize(~D[4660-04-01 Cldr.Calendar.Chinese], :day_of_week, locale: :zh)\n\"周四\"\n```\n\n## Relationship to other libraries\n\nThis library is part of the [CLDR](https://cldr.unicode.org)-based libraries for Elixir including:\n\n* [ex_cldr](https://hex.pm/packages/ex_cldr)\n* [ex_cldr_numbers](https://hex.pm/packages/ex_cldr_numbers)\n* [ex_cldr_dates_times](https://hex.pm/packages/ex_cldr_dates_times)\n* [ex_cldr_units](https://hex.pm/packages/ex_cldr_units)\n* [ex_cldr_lists](https://hex.pm/packages/ex_cldr_lists)\n* [ex_cldr_messages](https://hex.pm/packages/ex_cldr_messages)\n* [ex_cldr_calendars](https://hex.pm/packages/ex_cldr_calendars)\n* [ex_cldr_currencies](https://hex.pm/packages/ex_cldr_currencies)\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-cldr%2Fcldr_calendars_lunisolar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felixir-cldr%2Fcldr_calendars_lunisolar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felixir-cldr%2Fcldr_calendars_lunisolar/lists"}