# English Conversion Guide

Version: 1.0.0-public  
Date: 2026-03-20  
License: jp-election-data License v1.0

---

## 1. Scope

This guide explains how to derive English-facing labels from the public dataset.

It does **not** redefine canonical keys.
Canonical identifiers remain Japanese/JIS-anchored.

---

## 2. Canonical Keys Stay Japanese

Use these fields as the source of truth:

- `prefecture_code`
- `jis_code`
- `party_id`
- `election_key`

English labels are presentation-layer derivatives only.

Do not use English strings as join keys when the canonical code exists.

---

## 3. Municipality Names

### 3.1 Source Priority

Use the following priority order:

1. `gazetteer_japan_2021.csv`
2. `municipality_romanization_overrides.csv`
3. leave blank or mark unresolved

### 3.2 Interpretation

- `gazetteer_japan_2021.csv` is the primary public reference
- `municipality_romanization_overrides.csv` is a reviewed supplement for cases not covered cleanly by the Gazetteer
- unresolved names should not be guessed silently

### 3.3 Recommended Output Fields

If you materialize English-facing municipality names, keep these meanings distinct:

- `municipality_name_romanized_official`
- `municipality_name_romanized_effective`
- `romanization_status`
- `romanization_source`

---

## 4. Party Names

### 4.1 Source Priority

Use the following sequence:

1. normalize Japanese source labels with `party_alias.csv`
2. resolve to canonical `party_id`
3. map `party_id` to English with `party_master.csv:name_en`

### 4.2 Interpretation

- `party_alias.csv` is the public normalization table for Japanese ballot labels and short labels
- `party_master.csv` is the canonical table for party identity and English name
- English party labels should be derived from `party_id`, not from raw string guessing

---

## 5. What This Guide Does Not Do

This guide does not provide:

- machine translation of notes or residual reports
- a claim that all English labels are official government exonyms
- a replacement for canonical Japanese labels in fact tables

---

## 6. Practical Rule

For downstream English-facing use:

- join on codes
- display English labels when available
- preserve Japanese originals
- keep unresolved cases explicit instead of silently inventing names