Convert a Japanese era year to a Western (Gregorian) year.

Args: era_year: An era-year string. Accepts kanji form ('令和8年', '令和8', '令和元年'), single-letter alias ('R8', 'H30'), or English alias ('Reiwa 8', 'Heisei 30').

Returns: dict with keys: - western_year: int (Gregorian year) - era_kanji: str (e.g. '令和') - era_english: str (e.g. 'Reiwa') - year_of_era: int

Examples: era_to_western("令和8年") → {"western_year": 2026, ...} era_to_western("R8") → {"western_year": 2026, ...} era_to_western("Reiwa 8") → {"western_year": 2026, ...}

Convert a Western (Gregorian) year to its Japanese era year.

Note: this returns the era in effect for the majority of the given Gregorian year. For year transitions (e.g. 1989 split between 昭和64 and 平成1), it returns the newer era.

Args: year: Western year (e.g. 2026). Must be 1868 or later.

Returns: dict with keys: - era_kanji: str - era_english: str - year_of_era: int (1 for the first year of an era; written as 元年 in formal Japanese) - era_year_kanji: str (e.g. '令和8年') - era_year_short: str (e.g. 'R8')

Examples: western_to_era(2026) → {"era_kanji": "令和", "era_english": "Reiwa", "year_of_era": 8, "era_year_kanji": "令和8年", "era_year_short": "R8"}

Transliterate Japanese text (kanji + kana mix) to Hepburn romaji.

Args: text: Japanese text. May contain kanji, hiragana, katakana, ASCII. Non-Japanese characters pass through unchanged.

Returns: dict with keys: - romaji: str (space-separated Hepburn romaji) - hiragana: str (kanji converted to hiragana, kana preserved) - input: str (echo of the original input)

Examples: kanji_to_romaji("山田太郎") → {"romaji": "yamada tarou", "hiragana": "やまだたろう"} kanji_to_romaji("東京駅") → {"romaji": "toukyou eki", "hiragana": "とうきょうえき"}

Caveats: - Kanji with multiple readings (e.g. proper nouns) may be ambiguous. The transliteration uses the most common reading, which is sometimes wrong for personal names. Use as a starting point, not a guarantee.

Look up a Japanese postal code (郵便番号) and return address components.

Args: postal_code: 7-digit JP postal code. Accepts '150-0001', '1500001', '150 0001', or with full-width digits.

Returns: dict with keys: - postal_code: str (normalized 7-digit form) - prefecture: str (都道府県) - city: str (市区町村) - area: str (町域 — neighborhood/area) - prefecture_kana: str (katakana reading of prefecture) - city_kana: str - area_kana: str - found: bool (true if the code resolved)

Examples: lookup_postal_code("150-0001") → { "postal_code": "1500001", "prefecture": "東京都", "city": "渋谷区", "area": "神宮前", ... "found": True, }

Check whether a date is a Japanese national holiday (祝日).

Args: date_str: Date in 'YYYY-MM-DD', 'YYYY/MM/DD', or 'YYYYMMDD' format.

Returns: dict with keys: - date: str (normalized 'YYYY-MM-DD') - is_holiday: bool - name_jp: str | None (holiday name in Japanese, if applicable) - weekday_jp: str (e.g. '月', '火', ...) - weekday_en: str (e.g. 'Monday')

Examples: is_holiday("2026-05-03") → {"is_holiday": True, "name_jp": "憲法記念日", ...} is_holiday("2026-05-04") → {"is_holiday": True, "name_jp": "みどりの日", ...} is_holiday("2026-05-08") → {"is_holiday": False, "name_jp": None, ...}

Notes: - Covers national holidays only (祝日 designated by the 国民の祝日に関する法律). Does not cover company-specific or regional observances. - 振替休日 (substitute holidays) are correctly identified.

List all Japanese national holidays for a given year.

Args: year: Western year (e.g. 2026).

Returns: dict with keys: - year: int - count: int - holidays: list of {date: 'YYYY-MM-DD', name_jp: str, weekday_en: str}

Examples: list_holidays(2026) → {"year": 2026, "count": 16, "holidays": [...]}

Convert between hiragana, katakana, and half-width katakana.

Args: text: Input string. Mix of hiragana, katakana, kanji, ASCII is fine — non-target characters pass through unchanged. to: Target script. One of: - 'hiragana' : ひらがな (e.g. ヤマダ → やまだ) - 'katakana' : カタカナ (full-width) (e.g. やまだ → ヤマダ) - 'half_kana' : ﾊﾝｶｸｶﾀｶﾅ (half-width katakana) (e.g. ヤマダ → ﾔﾏﾀﾞ) - 'full_kana' : ヤマダ (half-width → full-width katakana)

Returns: dict with keys: - input: str - output: str - to: str

Examples: convert_kana("ヤマダタロウ", "hiragana") → "やまだたろう" convert_kana("やまだたろう", "katakana") → "ヤマダタロウ" convert_kana("ヤマダ", "half_kana") → "ﾔﾏﾀﾞ" convert_kana("ﾔﾏﾀﾞ", "full_kana") → "ヤマダ"

Convert between half-width (半角) and full-width (全角) characters.

Args: text: Input string. mode: Conversion direction. One of: - 'to_full' : half-width → full-width for all categories (kana, ascii, digits) - 'to_half' : full-width → half-width for all categories - 'to_full_ascii_only' : convert only ASCII letters and digits to full-width, leave kana untouched - 'to_half_ascii_only' : convert only full-width ASCII to half-width - 'to_full_kana_only' : convert only half-width katakana to full-width - 'to_half_kana_only' : convert only full-width katakana to half-width

Returns: dict with keys: - input: str - output: str - mode: str

Examples: normalize_width("ＡＢＣ１２３", "to_half") → "ABC123" normalize_width("ABC123", "to_full") → "ＡＢＣ１２３" normalize_width("ｶﾀｶﾅ", "to_full") → "カタカナ"

Split a Japanese full name into surname (姓) and given name (名).

Uses a kanji-feature-based statistical model (namedivider-python).

Args: full_name: Japanese full name written in kanji, with no separator (e.g. '山田太郎', '長谷川健太'). Names with existing separators (space, comma) are also accepted — the separator will be re-detected.

Returns: dict with keys: - input: str - family: str (姓 — surname) - given: str (名 — given name) - confidence: float (0.0–1.0; higher = more confident split) - algorithm: str (which underlying algorithm produced the split)

Examples: split_japanese_name("山田太郎") → {"family": "山田", "given": "太郎", ...} split_japanese_name("長谷川健太") → {"family": "長谷川", "given": "健太", ...} split_japanese_name("佐藤花子") → {"family": "佐藤", "given": "花子", ...}

Caveats: - Statistical model — not 100% accurate, especially for unusual names or non-traditional name compositions. - Confidence < 0.5 indicates an ambiguous split; treat with caution. - Single-kanji surnames + single-kanji given names (e.g. '林修') are fundamentally ambiguous without external context.