{"id":30069484,"url":"https://github.com/agusmade/colloquial-time","last_synced_at":"2025-09-02T13:42:47.243Z","repository":{"id":268635505,"uuid":"889976783","full_name":"agusmade/colloquial-time","owner":"agusmade","description":"A lightweight library to express time in colloquial, human-friendly phrases for various languages","archived":false,"fork":false,"pushed_at":"2024-11-17T18:19:52.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T11:57:02.131Z","etag":null,"topics":["colloquialisms","human-readable","localization","multi-language","natural-language-generation","spoken-language","time-formatting"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agusmade.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-11-17T17:58:41.000Z","updated_at":"2024-11-18T00:55:53.000Z","dependencies_parsed_at":"2024-12-18T01:49:09.456Z","dependency_job_id":"d26d0217-f696-4e36-a8d0-42160ffb2337","html_url":"https://github.com/agusmade/colloquial-time","commit_stats":null,"previous_names":["agusmade/colloquial-time"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/agusmade/colloquial-time","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmade%2Fcolloquial-time","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmade%2Fcolloquial-time/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmade%2Fcolloquial-time/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmade%2Fcolloquial-time/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agusmade","download_url":"https://codeload.github.com/agusmade/colloquial-time/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agusmade%2Fcolloquial-time/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273114744,"owners_count":25048253,"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","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["colloquialisms","human-readable","localization","multi-language","natural-language-generation","spoken-language","time-formatting"],"created_at":"2025-08-08T11:41:28.992Z","updated_at":"2025-09-02T13:42:47.220Z","avatar_url":"https://github.com/agusmade.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Colloquial Time 🕒\n\n**Making time human-friendly with natural, everyday expressions.**\n\nWhy stick with \"07:15\" when you can say \"quarter past seven\" or \"setengah delapan\"? This library helps you express time the way people actually talk—casual, natural, and easy to understand.\n\n---\n\n## What’s This About? 🤔\n\n`colloquial-time` is a lightweight JavaScript library for formatting time into everyday, spoken expressions. It focuses on practicality and real-world use, steering away from overly formal or robotic language.\n\n### Features ✨\n\n-   **Localized Expressions**: Supports multiple languages, from English to Indonesian, Japanese, Russian, and more.\n-   **Zero Dependencies**: Simple and efficient—no external dependencies required.\n-   **Natural Style**: Prioritizes spoken language for casual conversations.\n-   **Special Cases**: Includes \"midnight\" and \"noon\" handling where relevant.\n-   **Customizable**: Create or tweak configurations to fit specific languages or regional dialects.\n\n---\n\n## Installation 🚀\n\nInstall via npm or yarn:\n\n```bash\nnpm install colloquial-time\n```\n\nor\n\n```bash\nyarn add colloquial-time\n```\n\n---\n\n## Usage 💻\n\nGet started in seconds:\n\n```javascript\nconst {colloquial, languages} = require('colloquial-time');\n\n// English Example\nconsole.log(colloquial(new Date(), languages.en)); // \"quarter past seven in the morning\"\n\n// Indonesian Example\nconsole.log(colloquial(new Date(), languages.id)); // \"jam tujuh lewat seperempat pagi\"\n```\n\n---\n\n## Supported Languages 🌍\n\n-   🇮🇩 **Indonesian** (Bahasa Indonesia)\n-   🇬🇧 **English**\n-   🇩🇪 **German** (Deutsch)\n-   🇷🇺 **Russian** (Русский)\n-   🇫🇷 **French** (Français)\n-   🇪🇸 **Spanish** (Español)\n-   🇯🇵 **Japanese** (日本語)\n-   🇨🇳 **Chinese** (中文)\n\n### Bonus Examples 🎉\n\nWhile not a primary focus, the library also supports:\n\n-   **Balinese** (Bahasa Bali)\n-   **Javanese** (Bahasa Jawa)\n-   **Sundanese** (Bahasa Sunda)\n\nThese examples highlight how the library can accommodate regional and underrepresented languages, showcasing its flexibility.\n\n---\n\n## API 📚\n\n### `colloquial(date: Date, langConfig: LanguageConfig): string`\n\n**Parameters:**\n\n-   `date`: A JavaScript `Date` object or a date string.\n-   `langConfig`: Language configuration object (e.g., `languages.en`).\n\n**Returns:**\n\n-   A human-readable, colloquial time expression.\n\n---\n\n## Custom Language Configurations 🛠️\n\nAdd your own language or modify existing ones. Here’s an example configuration for English:\n\n```javascript\nmodule.exports = {\n  numbers: ['', 'one', 'two', 'three', ...],\n  minutePrepositions: { 5: 'five', 10: 'ten', ... },\n  halfHourPrepositions: { 15: 'quarter', 30: 'half' },\n  timeOfDay: [\n    [0, 11, 'in the morning'],\n    [12, 17, 'in the afternoon'],\n    [18, 23, 'in the evening']\n  ],\n  words: {\n    timePrefix: '',\n    hourSuffix: \" o'clock\",\n    less: 'to',\n    more: 'past',\n  },\n  format: {\n    exactHour: '{hour}{hourSuffix} {timeOfDay}',\n    pastMinutes: '{minutes} {more} {hour} {timeOfDay}',\n    toMinutes: '{minutes} {less} {hour} {timeOfDay}',\n  },\n};\n```\n\n---\n\n## Why Colloquial? 🤷\n\nThis library isn’t just about showing time; it’s about making time relatable. Whether you're coding for chatbots, smart devices, or just having fun with time formats, `colloquial-time` keeps things friendly and easy to understand.\n\n---\n\n## Limitations and Contributions ✋\n\n-   **Not Perfect Yet**: While the library supports many languages, the phrasing may not always align perfectly with everyday local expressions. Contributions are welcome to refine this! 🌍\n-   **Got Feedback?**: Found a better way to phrase time in your language? Share it! Let’s make this better together.\n-   **Add New Languages**: Want to see your language represented? Feel free to submit a configuration for it! Even lesser-known or regional languages are more than welcome. 🗣️\n-   **Expand Features**: Have ideas for improving functionality or making the library more flexible? Contributions for additional features or edge cases are encouraged. ✨\n\nYour input helps us make this library truly relatable across diverse cultures and communities! 🙌\n\n### How to Contribute 🛠️\n\nWant to help improve `colloquial-time`? Awesome! Here’s how you can pitch in:\n\n1. **Fork the Repository**: Start by forking this repo to your GitHub account.\n\n2. **Clone Your Fork**: Clone the forked repo to your local machine:\n\n    ```bash\n    git clone https://github.com/your-username/colloquial-time.git\n    ```\n\n3. **Create a Branch**: Create a branch for your contribution:\n    ```bash\n    git checkout -b feature/new-language\n    ```\n4. **Make Your Changes**: Add or update language configurations, improve phrasing, or suggest new features.\n5. **Test Your Changes**: Run the test suite to ensure everything works:\n\n    ```bash\n    yarn test\n    ```\n\n    Example Output:\n\n    ```\n    Running tests...\n    ✓ Indonesian - Exact hour\n    ✓ Indonesian - Quarter past\n    ✓ Japanese - Half past\n    ✓ French - Midnight\n    ✅ All 63 tests passed!\n    ```\n\n6. **Commit Your Work**: Write a meaningful commit message:\n    ```bash\n    git commit -m \"Add support for Klingon language 🖖\"\n    ```\n7. **Push Your Branch**: Push the branch to your fork:\n    ```bash\n    git push origin feature/new-language\n    ```\n8. **Open a Pull Request**: Go to the original repo and open a pull request. Be sure to include a clear description of what you’ve added or fixed.\n\n---\n\n## License 📄\n\nMIT. Feel free to use, share, and improve.\n\n---\n\n## Author 🎨\n\nCreated with care by **Agus Made**. For feedback or inquiries, feel free to reach out via [GitHub](https://github.com/agusmade).\n\n---\n\n## Examples in Action 🎬\n\n```javascript\nconst {colloquial, languages} = require('colloquial-time');\n\n// Russian\nconsole.log(colloquial(new Date('2024-11-16T07:15:00'), languages.ru)); // \"четверть восьмого утра\"\n\n// Japanese\nconsole.log(colloquial(new Date('2024-11-16T07:30:00'), languages.ja)); // \"七時三十分 午前\"\n\n// French\nconsole.log(colloquial(new Date('2024-11-16T07:45:00'), languages.fr)); // \"huit heures moins le quart du matin\"\n```\n\n---\n\nLet’s make telling time fun again! 🕰️\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagusmade%2Fcolloquial-time","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagusmade%2Fcolloquial-time","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagusmade%2Fcolloquial-time/lists"}