Skip to content

docs: add English README for international / expat audience#18

Merged
redchupa merged 1 commit into
mainfrom
docs/readme-english
May 13, 2026
Merged

docs: add English README for international / expat audience#18
redchupa merged 1 commit into
mainfrom
docs/readme-english

Conversation

@redchupa
Copy link
Copy Markdown
Owner

Adds `README.en.md` alongside the Korean README for HACS Default discovery + international visitors arriving via search.

Why

When this lands on HACS Default + community posts, the audience is broader than Korean residents alone:

  • Korean expats abroad monitoring family-home utilities or disaster alerts back home
  • Foreigners living in Korea running HA, fluent enough in Korean to use the actual services but more comfortable reading English docs
  • International HA users integrating Korean air-quality / weather data into a global setup (e.g., overseas Koreans tracking PM2.5 in Seoul)

A literal translation of the Korean README would miss several pain points specific to this audience:

  1. Agency-name disambiguation — multiple Korean government portals are involved (NMC, KMA, KECO, NEIS, MOIS, Seoul Metropolitan Government). English readers need explicit context.
  2. Untranslated Korean GUI labels — HA shows the Korean labels as-is (`한국 컴포넌트 키트`, `최신 안전알림`, `수용가번호`). The English version leaves these as-is and adds English context alongside, so the reader knows what to type/look for in the actual HA UI.
  3. 시도 / 시군구 / 읍면동 explanation — administrative hierarchy needs a one-time gloss for non-Koreans.

What's in it

Same structure as the Korean README:

  • 5-minute quickstart (API-key-free Safety Alert demo)
  • 13 services overview table
  • 🔑 API key issuance guide with direct portal-search deep links (clickable 👉 links pre-filled with Korean search keywords — browsers auto-encode)
  • ⚙️ Registration / reconfiguration flow
  • 🎁 Entities-you-get reference table
  • 🤖 LLM voice-query examples
  • ❓ FAQ (10 items)
  • 🔄 Update intervals
  • ⚠️ Known limitations (honest disclosure)
  • 🐛 Troubleshooting
  • Requirements, Disclaimer, License

Top-of-Korean-README language toggle

Korean README now shows at the top:

```
🇰🇷 한국어 (이 페이지) · 🇬🇧 English README
```

GitHub renders both .md files; readers click the flag to switch.

🤖 Generated with Claude Code

Adds README.en.md alongside the existing Korean README, tailored for:
- Korean residents (including foreigners living in Korea) running HA
- Korean expats abroad monitoring family-home utilities or alerts
- Anyone integrating Korean weather / air-quality data into a global HA setup

The English version is not a literal translation — it's restructured for
readers who:
- Are fluent in HA terminology but may be new to Korean public services
- Need Korean GUI labels left untranslated (they appear as-is in HA) with
  English explanations alongside
- Need agency-name disambiguation (NMC, KMA, KECO, NEIS, MOIS) since
  multiple Korean government portals are involved

Same 5-minute quickstart, same direct portal search deep links (clickable
👉 links that land users on each portal's search-results page with the
Korean keyword pre-filled), same honest known-limitations disclosure.

Top of README.md now carries a 🇰🇷 / 🇬🇧 language toggle pointing at
README.en.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@redchupa redchupa merged commit 9f8ad17 into main May 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants