About koko ai

Why we built koko ai

Most Korean apps treat the language like a flashcard pile: memorize 5,000 words and you'll be fluent. In practice, the wall most learners hit isn't vocabulary; it's the four or five grammatical features Korean does very differently from English. Particles (은, 는, 이, 가, 을, 를) decide which noun is the subject and which is the topic. Honorifics decide whether your sentence sounds polite or rude. Sentence-final endings carry the formality register. Hangul itself is the easy part.

We built koko ai to lean into that reality. The app gives instant pronunciation feedback so you can hear when 어 and 오 are different. The dictionary explains when a word is used, not just what it means. The blog uses real K-pop and K-drama examples (verified, never invented) so the cultural context lands with the grammar.

• Pronunciation-first: every word page has TTS audio (Azure / Google Cloud) so you can hear native pronunciation before you try to say it.
• Real K-content examples: example sentences come from everyday Korean, K-drama dialogue, and K-pop lyrics — never machine-invented quotes.
• Grammar pillars over flashcards: long-form pages on Hangul, particles, and honorifics that you can read in one sitting.
• Multilingual: the dictionary and blog ship in 9 non-English locales (Spanish, Portuguese-BR, Japanese, Traditional Chinese, Indonesian, Vietnamese, German, French, Thai).

Editorial standards

Korean-learning content on the open web has a quality problem. Romanizations disagree with each other, K-pop lyrics get hallucinated, and "casual vs formal" tables routinely contradict what Koreans actually say. The rules below are the editorial floor for everything we publish.

• Native or near-native review. All Korean content is reviewed by a native Korean speaker or by a contributor with Korean Language Institute teaching experience before it goes live.
• Citations limited to a verified whitelist. Facts about K-pop songs, K-drama scenes, lyrics, and release dates may only come from a versioned data/blog-citations.json file. Each entry is cross-checked against Wikipedia, Naver, and the artist's official channel. The drafting prompt cannot reference any song, drama, or quote that is not on the list.
• No invented facts. If a fact about a K-pop song or K-drama scene isn't in the citation file, we don't include it. We would rather ship a slightly drier paragraph than a confidently wrong one.
• AI-assisted drafting, human-rule validation. Long-form posts and word pages are drafted with Claude Code (this CLI) running on a cron, then validated by a deterministic Python script (scripts/blog-validate.py) that enforces voice rules: em-dash budget, contractions allowed, FAQ section required, at least five internal /word/ links per post, image present, etc. Drafts that fail validation never reach the site.
• Translations are deterministic and source-tracked. Non-English locale content is translated through a separate batch (scripts/translate-blog.py) and pinned to a source-content hash so a re-translation only triggers when the English source actually changed.
• Updates are dated. Every article shows a published date and an updated date. We don't silently rewrite history.

Our sources

We pull from a small number of well-respected, primary references. The citation file is public to contributors and gets pull requests when an entry needs updating.

• K-pop song facts: the artist's official channel, Billboard, and Naver's music database. Lyric quotes only when verified against an officially published lyric video or label release.
• K-drama references: official channel descriptions, MBC / tvN / SBS publicity material, and Naver's drama database. Scene descriptions come from the licensed broadcast, never from fan transcripts.
• Korean grammar: the National Institute of the Korean Language (국립국어원) standard reference, plus textbook grammar from Yonsei Korean Language Institute and Talk To Me In Korean's curriculum.
• Vocabulary frequency: the National Institute of Korean Language frequency list (modern Korean corpus) and KAIST's open Korean NLP data.
• Romanization: the Revised Romanization of Korean (RR) system, which is the South Korean government standard since 2000.

How we generate content

We keep the pipeline transparent so readers can judge it for themselves.

1. Daily blog cron, 23:00 KST. A cron on the editor's MacBook picks one queued topic from data/blog-queue.json, opens a draft session in Claude Code, and writes a JSON file under content/blog/_pending/.
2. Deterministic validation gate. scripts/blog-validate.py rejects drafts that miss any of: at least five /word/ internal links, a "Common questions" H2 section with three or more H3 questions, contractions allowed by the voice rules, em-dash count under the budget, hero image present, accurate reading time. Failed drafts stay in _pending for revision.
3. Hero image, budget-capped. scripts/blog-image.py calls Gemini Imagen for a single hero image. A spend log (data/blog-spend-log.json) hard-caps spend at $1/day and $10/month and aborts the run with a GitHub issue if the cap is hit. No text content is ever generated by an external LLM API on this site — text is authored only by Claude Code from this CLI.
4. Translation pass. A separate batch translates the validated post into 9 locales using Gemini 2.0 Flash. Each translation is keyed to a hash of the source so we don't pay to re-translate unchanged posts.
5. Publish, sitemap, indexing. The post is committed by izr8809, the sitemap regenerates, and the URL is submitted to the Google Indexing API.

The full pipeline is documented in BLOG_PLAN.md in the open source repository. The validation rules in SEO_GUIDELINES.md and the voice rules in AI_VOICE_GUIDE.md are versioned in the same repo.

Contributors

koko ai's content is written and reviewed by a small group of contributors with mixed Korean-language and Korean-culture backgrounds.

Meet the authors →

Contact

Spotted an error in a translation, a hallucinated K-pop fact, or a grammar example that doesn't match how Koreans actually talk? Tell us. We treat corrections as the highest-priority issue type.

• Email: izr8809@gmail.com
• GitHub: @izr8809