Colloquial Time 🕒

Making time human-friendly with natural, everyday expressions.

Why 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.

What’s This About? 🤔

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.

Features ✨

• Localized Expressions: Supports multiple languages, from English to Indonesian, Japanese, Russian, and more.
• Zero Dependencies: Simple and efficient—no external dependencies required.
• Natural Style: Prioritizes spoken language for casual conversations.
• Special Cases: Includes "midnight" and "noon" handling where relevant.
• Customizable: Create or tweak configurations to fit specific languages or regional dialects.

Installation 🚀

Install via npm or yarn:

npm install colloquial-time

or

yarn add colloquial-time

Usage 💻

Get started in seconds:

const {colloquial, languages} = require('colloquial-time');

// English Example
console.log(colloquial(new Date(), languages.en)); // "quarter past seven in the morning"

// Indonesian Example
console.log(colloquial(new Date(), languages.id)); // "jam tujuh lewat seperempat pagi"

Supported Languages 🌍

• 🇮🇩 Indonesian (Bahasa Indonesia)
• 🇬🇧 English
• 🇩🇪 German (Deutsch)
• 🇷🇺 Russian (Русский)
• 🇫🇷 French (Français)
• 🇪🇸 Spanish (Español)
• 🇯🇵 Japanese (日本語)
• 🇨🇳 Chinese (中文)

Bonus Examples 🎉

While not a primary focus, the library also supports:

• Balinese (Bahasa Bali)
• Javanese (Bahasa Jawa)
• Sundanese (Bahasa Sunda)

These examples highlight how the library can accommodate regional and underrepresented languages, showcasing its flexibility.

API 📚

colloquial(date: Date, langConfig: LanguageConfig): string

Parameters:

• date: A JavaScript Date object or a date string.
• langConfig: Language configuration object (e.g., languages.en).

Returns:

• A human-readable, colloquial time expression.

Custom Language Configurations 🛠️

Add your own language or modify existing ones. Here’s an example configuration for English:

module.exports = {
  numbers: ['', 'one', 'two', 'three', ...],
  minutePrepositions: { 5: 'five', 10: 'ten', ... },
  halfHourPrepositions: { 15: 'quarter', 30: 'half' },
  timeOfDay: [
    [0, 11, 'in the morning'],
    [12, 17, 'in the afternoon'],
    [18, 23, 'in the evening']
  ],
  words: {
    timePrefix: '',
    hourSuffix: " o'clock",
    less: 'to',
    more: 'past',
  },
  format: {
    exactHour: '{hour}{hourSuffix} {timeOfDay}',
    pastMinutes: '{minutes} {more} {hour} {timeOfDay}',
    toMinutes: '{minutes} {less} {hour} {timeOfDay}',
  },
};

Why Colloquial? 🤷

This 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.

Limitations and Contributions ✋

• 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! 🌍
• Got Feedback?: Found a better way to phrase time in your language? Share it! Let’s make this better together.
• 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. 🗣️
• Expand Features: Have ideas for improving functionality or making the library more flexible? Contributions for additional features or edge cases are encouraged. ✨

Your input helps us make this library truly relatable across diverse cultures and communities! 🙌

How to Contribute 🛠️

Want to help improve colloquial-time? Awesome! Here’s how you can pitch in:

1. Fork the Repository: Start by forking this repo to your GitHub account.

2. Clone Your Fork: Clone the forked repo to your local machine:

   git clone https://github.com/your-username/colloquial-time.git

3. Create a Branch: Create a branch for your contribution:

   git checkout -b feature/new-language

4. Make Your Changes: Add or update language configurations, improve phrasing, or suggest new features.

5. Test Your Changes: Run the test suite to ensure everything works:

   yarn test

   Example Output:

   Running tests...
   ✓ Indonesian - Exact hour
   ✓ Indonesian - Quarter past
   ✓ Japanese - Half past
   ✓ French - Midnight
   ✅ All 63 tests passed!

6. Commit Your Work: Write a meaningful commit message:

   git commit -m "Add support for Klingon language 🖖"

7. Push Your Branch: Push the branch to your fork:

   git push origin feature/new-language

8. 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.

License 📄

MIT. Feel free to use, share, and improve.

Author 🎨

Created with care by Agus Made. For feedback or inquiries, feel free to reach out via GitHub.

Examples in Action 🎬

const {colloquial, languages} = require('colloquial-time');

// Russian
console.log(colloquial(new Date('2024-11-16T07:15:00'), languages.ru)); // "четверть восьмого утра"

// Japanese
console.log(colloquial(new Date('2024-11-16T07:30:00'), languages.ja)); // "七時三十分 午前"

// French
console.log(colloquial(new Date('2024-11-16T07:45:00'), languages.fr)); // "huit heures moins le quart du matin"

Let’s make telling time fun again! 🕰️