kotowaza

v1.0.1

Published

24 days ago

Structured JSON dataset of Japanese proverbs (kotowaza) with meanings in Indonesian & English, example sentences, JLPT levels, and tags.

0High
0Medium
0Low

septn

kotowaza proverb japanese peribahasa idiom jlpt data jepang indonesia language learning nihongo

Kotowaza — Japanese Proverbs Dataset 📚

A structured, production-grade dataset of Japanese proverbs (ことわざ / Kotowaza) with bilingual meanings, example sentences, JLPT levels, and thematic tags.

⚡️ Live Demo: This dataset powers the Kamus Peribahasa Jepang on Jepang.org — Indonesia's comprehensive Japanese learning platform. See it running in production!

Repository: github.com/sepTN/kotowaza
Documentation: septn.github.io/kotowaza
Website: Jepang.org — Belajar Bahasa Jepang

Features

📖 Bilingual Meanings — Each entry includes explanations in Indonesian and English
🈁 Complete Readings — Hiragana (reading), romaji, and original kanji
📝 Example Sentences — Real-world usage with Japanese, romaji, and Indonesian translation
🏷️ Thematic Tags — Categorized by theme (animals, life, money, relationships, etc.)
📊 JLPT Levels — Entries tagged with JLPT N5–N1 difficulty levels
🔗 Related Proverbs — Cross-references to similar or related kotowaza
🌐 Equivalent Proverbs — Matching proverbs in Indonesian and English
⚡ Zero Dependencies — Pure JSON data with lightweight query helpers
🔍 Built-in Search — Search across all text fields instantly

Installation

npm install kotowaza

Quick Start

const kotowaza = require('kotowaza');

// Get all entries
const all = kotowaza.all();
console.log(`Loaded ${kotowaza.count()} proverbs`);

// Look up a specific proverb by ID
const entry = kotowaza.get('nanakorobi-yaoki');
console.log(entry.japanese);    // 七転び八起き
console.log(entry.meaning.en);  // No matter how many times you fail...

// Search across all fields (Japanese, romaji, or meaning)
kotowaza.search('猿');           // → entries containing 猿
kotowaza.search('monkey');       // → entries with "monkey" in English

// Filter by theme tag
kotowaza.byTag('motivation');    // → motivational proverbs
kotowaza.byTag('animals');       // → animal-related proverbs

// Filter by Indonesian tag
kotowaza.byTagId('motivasi');    // → same as byTag('motivation')

// Filter by JLPT level
kotowaza.byJlpt('N3');          // → proverbs suitable for N3

// Get a random proverb (great for "Quote of the Day" features!)
const daily = kotowaza.random();
console.log(`${daily.japanese} — ${daily.meaning.id}`);

// Get all available tags and JLPT levels
kotowaza.tags();                 // → ['animals', 'business', 'culture', ...]
kotowaza.tagsId();               // → ['angka', 'bisnis', 'budaya', ...]
kotowaza.jlptLevels();           // → ['N2', 'N3', 'N4']

// Generate a link to the full article on Jepang.org
kotowaza.url('nanakorobi-yaoki');
// → https://jepang.org/peribahasa/nanakorobi-yaoki/

Examples

📅 Quote of the Day

const kotowaza = require('kotowaza');

// Deterministic "daily" proverb based on the date
function getDailyProverb() {
    const all = kotowaza.all();
    const today = new Date();
    const dayIndex = (today.getFullYear() * 366 + today.getMonth() * 31 + today.getDate()) % all.length;
    return all[dayIndex];
}

const daily = getDailyProverb();
console.log(`📜 ${daily.japanese}`);
console.log(`💬 ${daily.meaning.en}`);
// 📜 七転び八起き
// 💬 No matter how many times you fail, never give up...

🌐 Express API Endpoint

const express = require('express');
const kotowaza = require('kotowaza');
const app = express();

// GET /api/proverbs?tag=motivation&jlpt=N3
app.get('/api/proverbs', (req, res) => {
    let results = kotowaza.all();

    if (req.query.tag) {
        results = kotowaza.byTag(req.query.tag);
    }
    if (req.query.jlpt) {
        results = results.filter(e => e.jlpt === req.query.jlpt.toUpperCase());
    }
    if (req.query.q) {
        results = kotowaza.search(req.query.q);
    }

    res.json({ count: results.length, data: results });
});

// GET /api/proverbs/random
app.get('/api/proverbs/random', (req, res) => {
    res.json(kotowaza.random());
});

// GET /api/proverbs/:id
app.get('/api/proverbs/:id', (req, res) => {
    const entry = kotowaza.get(req.params.id);
    if (!entry) return res.status(404).json({ error: 'Not found' });
    res.json(entry);
});

🎓 JLPT Study Flashcards

const kotowaza = require('kotowaza');

// Build a study deck for a specific JLPT level
function buildStudyDeck(level) {
    return kotowaza.byJlpt(level).map(entry => ({
        front: entry.japanese,
        hint: entry.reading,
        back: entry.meaning.en,
        example: entry.examples[0]?.ja,
        url: kotowaza.url(entry.id)
    }));
}

const n3Deck = buildStudyDeck('N3');
console.log(`📚 ${n3Deck.length} flashcards for JLPT N3`);

// Shuffle and quiz
const card = n3Deck[Math.floor(Math.random() * n3Deck.length)];
console.log(`Q: What does "${card.front}" mean?`);
console.log(`A: ${card.back}`);

🔎 Search Autocomplete

const kotowaza = require('kotowaza');

// Lightweight search for autocomplete / typeahead
function autocomplete(query) {
    if (!query || query.length < 2) return [];

    return kotowaza.search(query).slice(0, 5).map(entry => ({
        id: entry.id,
        label: `${entry.japanese} (${entry.romaji})`,
        preview: entry.meaning.en.slice(0, 60) + '...'
    }));
}

console.log(autocomplete('fall'));
// [{ id: 'nanakorobi-yaoki', label: '七転び八起き (Nanakorobi Yaoki)', preview: '...' }]

🤖 Discord / Slack Bot

const kotowaza = require('kotowaza');

// !kotowaza — random proverb
function handleCommand(command, args) {
    if (command === '!kotowaza') {
        const entry = args[0] ? kotowaza.get(args[0]) : kotowaza.random();
        if (!entry) return '❌ Proverb not found.';

        return [
            `**${entry.japanese}** (${entry.romaji})`,
            `> _${entry.meaning.en}_`,
            entry.equivalent?.en ? `🔗 Similar: "${entry.equivalent.en}"` : '',
            `📖 ${kotowaza.url(entry.id)}`
        ].filter(Boolean).join('\n');
    }

    // !kotowaza-quiz — quiz mode
    if (command === '!kotowaza-quiz') {
        const entry = kotowaza.random();
        return `❓ What does **"${entry.japanese}"** mean?\n||${entry.meaning.en}||`;
    }
}

🏗️ Static Site Generator (11ty / Hugo / Astro)

const kotowaza = require('kotowaza');

// Generate pages for each proverb (e.g. in 11ty .eleventy.js)
module.exports = function(eleventyConfig) {
    eleventyConfig.addCollection('proverbs', () => {
        return kotowaza.all().map(entry => ({
            ...entry,
            permalink: `/proverbs/${entry.id}/`,
            fullUrl: kotowaza.url(entry.id)
        }));
    });

    // Shortcode for embedding a random proverb
    eleventyConfig.addShortcode('randomProverb', () => {
        const p = kotowaza.random();
        return `<blockquote class="kotowaza">
            <p lang="ja">${p.japanese}</p>
            <footer>${p.meaning.en}</footer>
        </blockquote>`;
    });
};

API Reference

Data Schema

Each entry follows this structure:

{
  "id": "nanakorobi-yaoki",        // URL slug (matches jepang.org URL)
  "japanese": "七転び八起き",         // Original Japanese (kanji)
  "reading": "ななころびやおき",       // Hiragana reading
  "romaji": "Nanakorobi Yaoki",     // Romanized reading
  "literal": "Fall seven times, rise eight times", // Literal translation
  "meaning": {
    "id": "Indonesian meaning...",  // Meaning in Bahasa Indonesia
    "en": "English meaning..."      // Meaning in English
  },
  "tags": ["motivation", "numbers"],  // Thematic tags (English)
  "tags_id": ["motivasi", "angka"],   // Thematic tags (Indonesian)
  "jlpt": "N4",                     // JLPT level (or null)
  "equivalent": {
    "id": "Padanan peribahasa Indonesia...",
    "en": "Equivalent English proverb..."
  },
  "examples": [                     // Example sentences
    {
      "ja": "Japanese sentence...",
      "romaji": "Romanized sentence...",
      "id": "Indonesian translation..."
    }
  ],
  "related": ["id-1", "id-2"]      // Related kotowaza IDs
}

Use Cases

🎓 Japanese Learning Apps — Quiz, flashcard, and study apps
🗓️ "Quote of the Day" — Use random() for daily proverb features
🤖 Chatbots — Enrich Japanese language bots with cultural wisdom
📱 Mobile Apps — Offline-ready, zero-dependency JSON dataset
🔬 NLP Research — Bilingual proverb corpus for language analysis
🎮 Games — Cultural trivia or educational game content

Available Tags

The dataset uses the following thematic categories:

Contributing

Want to add more kotowaza? PRs are welcome! Each entry should follow the schema above.

You can browse the full collection of 600+ proverbs on Jepang.org Peribahasa for reference.

About

This dataset is compiled and maintained by Septian Ganendra S. K., the Lead Maintainer at Jepang.org — Indonesia's comprehensive Japanese learning platform.

📚 If you use this package in your project, we'd appreciate a link back to Jepang.org! It helps us continue maintaining and expanding this free resource for Japanese learners worldwide.

Related Packages

kanji-png — Generate Kanji PNGs and animated stroke-order GIFs. Also by Jepang.org.