euskaphone 0.1.0a2__tar.gz

euskaphone-0.1.0a2/LICENSE

@@ -0,0 +1,204 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2021 Casimiro Ferreira
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+=======================================================================

euskaphone-0.1.0a2/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: euskaphone
+Version: 0.1.0a2
+Summary: Dialect-aware Basque (Euskara) text-to-IPA phonemizer over the orthography2ipa lattice
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/TigreGotico/euskaphone
+Project-URL: Repository, https://github.com/TigreGotico/euskaphone
+Keywords: basque,euskara,phonemizer,g2p,ipa,phonetics,tts,nlp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Basque
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: orthography2ipa>=7.28.0a1
+Requires-Dist: ovos-number-parser>=0.6.0a1
+Provides-Extra: langdetect
+Requires-Dist: markovonnx>=1.0.1; extra == "langdetect"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: markovonnx>=1.0.1; extra == "test"
+Dynamic: license-file
+
+# euskaphone
+
+Dialect-aware Basque (Euskara) text-to-IPA phonemizer — a TTS frontend built on
+the shared [orthography2ipa](https://github.com/TigreGotico/orthography2ipa)
+pronunciation lattice. euskaphone is the Basque sibling of
+[tugaphone](https://github.com/TigreGotico/tugaphone) (Portuguese) and
+[mwl_phonemizer](https://github.com/TigreGotico/mwl_phonemizer) (Mirandese), and
+is offered to the Basque research and speech-technology community as an open,
+inspectable, source-cited pipeline.
+
+A dialect *is* an orthography2ipa Basque lect spec: the spec's grapheme table,
+allophony and cross-word sandhi produce the dialect's phonology directly — the
+apical/laminal sibilant contrast, the affricates, Souletin aspiration and `/y/`.
+euskaphone adds only the stages orthography2ipa leaves to the caller.
+
+## Install
+
+```bash
+pip install euskaphone
+```
+
+## Quickstart
+
+```python
+from euskaphone import EuskaPhonemizer
+
+ph = EuskaPhonemizer()
+ph.phonemize_sentence("Zazpi katu zuri ikusi ditut.")          # Batua (default)
+# 's̻as̻pi katu s̻uɾi ikus̺i ditut'
+
+ph.phonemize_sentence("Hotza egiten du gaur mendian.", "souletin")
+# 'hots̻a eɡiten dy ɡauɾ mendian'   (Souletin: aspiration, /y/)
+```
+
+## Dialects
+
+Eight lects, selectable by BCP-47 code or by a human-readable alias:
+
+| code | dialect | aliases |
+|------|---------|---------|
+| `eu` | Standard Basque | `batua`, `standard` |
+| `eu-x-bizkaiera` | Biscayan | `biscayan`, `western` |
+| `eu-x-gipuzkera` | Gipuzkoan | `guipuzcoan`, `central` |
+| `eu-x-lapurtera` | Lapurdian | `labourdin` |
+| `eu-x-nafarra-garaia` | High Navarrese | `high-navarrese` |
+| `eu-x-nafarra-beherea` | Low Navarrese | `low-navarrese` |
+| `eu-x-zuberera` | Souletin | `souletin`, `xiberotarra` |
+| `eu-x-erronkariera` | Roncalese (†) | `roncalese` |
+
+## The three things euskaphone adds
+
+### 1. Vigesimal number normalization (the flagship)
+
+Basque cardinals are **base-20**: `hogei` (20), `berrogei` (40 = 2×20),
+`hirurogei` (60), `laurogei` (80); 30/50/70/90 are the preceding twenty *plus
+ten*; and the copulative `eta` ("and") contracts to `-ta` on the twenties.
+
+```python
+from euskaphone.number_utils import BasqueNumberParser, normalize_numbers
+
+p = BasqueNumberParser("eu")
+p.cardinal(31)     # 'hogeita hamaika'   (20-and-11)
+p.cardinal(1936)   # 'mila bederatziehun eta hogeita hamasei'
+p.ordinal(16)      # 'hamaseigarren'
+
+# case-suffixed numerals and clock time in running text (declension on the
+# last element of the numeral phrase)
+normalize_numbers("1936ko gerra", "eu")   # '… hogeita hamaseiko gerra'
+normalize_numbers("20:00etan", "eu")      # 'hogeietan'
+```
+
+Every base form is cited to **Euskaltzaindia Araua 7** (cardinals) and
+**Araua 18** (ordinals), and each is tagged attested-in-source vs derived-by-rule
+in `euskaphone.number_utils` (the `ATTESTED` / `DERIVED` sets). One notable
+correction the sources force: Araua 7 records `bost` (not `bortz`) for Zuberoa
+and most of Low Navarre, so euskaphone keeps `bost` everywhere by default and
+offers the `bortz` series only for Lapurdian — null beats a wrong dialect swap.
+See [`docs/numbers.md`](docs/numbers.md).
+
+### 2. Code-switch handling
+
+Real Basque text embeds Spanish (Hegoalde), French (Iparralde) and — in the
+tech/music/media register — English. Word-level detection identifies the embedded
+material, classifies each contact word **per word** among `es`/`fr`/`en`, routes
+it through the orthography2ipa `es-ES`/`fr-FR`/`en-US` lattice, and **nativizes**
+the result onto the Basque inventory (project every foreign phone onto its
+nearest Basque phone — never drop, always project). The `contact` parameter is
+`auto` (per-word detection), `es`, `fr`, `en`, or `none`.
+
+Detection prefers a small bundled **char-Markov language detector** (Basque /
+Spanish / French / English, ~180 KB total, scored by `markovonnx`; install with
+`euskaphone[langdetect]`) and falls back to an orthographic heuristic when the
+models are unavailable. Basque is the in-language default: a word is routed out
+of Basque only when a foreign model beats the Basque model by a clear margin (and
+short, plausibly-native words need orthographic corroboration), so a weak signal
+never misroutes a native word.
+
+```python
+ph.phonemize_sentence("Madrilen Plaza Mayor ikusi dut.", "eu")
+# '… plas̻a majoɾ …'  (Spanish routed + nativized: no θ, no stress)
+
+ph.phonemize_sentence("Streaming plataforma berria erabili dugu.")
+# 'strimin platafoɾma …'  (English routed + nativized onto the 5-vowel system)
+
+ph.phonemize_sentence("Maison Rouge etxean.", "souletin")
+# continental dialect → French contact by default
+```
+
+See [`docs/codeswitch.md`](docs/codeswitch.md).
+
+### 3. Lexicon hook + shipped lexicons
+
+`register_lexicon(dialect, source)` registers a proper-name/loan pronunciation
+table (the orthography2ipa lexicon contract: a `word<TAB>ipa` path, URL or
+`hf://` id); a covered word bypasses the lattice.
+
+Two lexicons ship built-in: a curated **Euskaltzaindia toponym seed** (on by
+default, `EuskaPhonemizer(toponyms=False)` to opt out) and an opt-in **HiTZ
+proper-noun overlay** (`EuskaPhonemizer(lexicon="hitz")`) that carries a
+benchmark circularity caveat. A caller's own lexicon always wins.
+See [`docs/lexicons.md`](docs/lexicons.md).
+
+### 4. Orthographic normalization
+
+Before the lattice runs, everything written as a symbol, abbreviation, Roman
+numeral or numeric date is spelled into Basque words
+(`euskaphone.normalize.normalize_text`, wired in as the orthography2ipa
+`normalize` stage):
+
+```python
+from euskaphone.normalize import normalize_text
+
+normalize_text("XX. mendean %20 igo da", "eu")
+# 'hogeigarren mendean ehuneko hogei igo da'
+normalize_text("Luis XIV.a errege zen", "eu")     # '… hamalaugarrena …'
+normalize_text("Sarrera €5eko da", "eu")          # '… bost euroko …'
+normalize_text("15/01/2024", "eu")   # 'bi mila eta hogeita lauko urtarrilaren hamabostean'
+```
+
+Roman-numeral ordinals (`XX.` → `hogeigarren`) and monarch numerals
+(`Luis XIV.a` → `hamalaugarrena`), a cited abbreviation list
+(`etab.` → `eta abar`), unit/currency/percent symbols with Basque word order and
+declension (`%5` and `5%` both → `ehuneko bost`), and numeric dates — each cited
+to Euskaltzaindia (Araua 18/37/196/197) and the EIMA *Ortotipografia* guide. The
+abbreviation and unit tables are expandable data files
+(`euskaphone/data/*.tsv`). See [`docs/normalization.md`](docs/normalization.md).
+
+### No homograph subsystem — by design
+
+Basque orthography is near-phonemic: a grapheme's reading is essentially fixed
+and sense-independent. Unlike tugaphone's Portuguese (which needs `bifonia` to
+resolve heterophonic homographs), euskaphone deliberately ships **no** homograph
+stage. This is a scope decision, documented so it is not mistaken for a gap.
+
+## OVOS plugin
+
+```python
+from euskaphone.plugin import EuskaphoneG2PPlugin
+EuskaphoneG2PPlugin("souletin").transcribe("kaixo mundua")
+```
+
+Registered under the `opm.g2p` entry-point group as `euskaphone`.
+
+## How it measures up
+
+euskaphone drives the shared orthography2ipa lattice, so it is only as accurate
+as that lattice — these numbers measure the lattice, honestly labelled. Run them
+with `python scripts/benchmark.py [--hitz]`.
+
+| gold | kind | figure |
+|------|------|--------|
+| orthography2ipa eu gold (166 rows, 8 lects) | **regression fixture** (same lattice made it) | PER `0.0000` — proves the lattice is untouched, *not* accuracy |
+| [WikiPron](https://github.com/CUNY-CL/wikipron) `eus_latn` broad | independent word gold | PER `0.0749`, word-acc `0.4563` (full set, 20,115 words) |
+| [HiTZ/EHU](https://huggingface.co/datasets/HiTZ/wikipedia_basque_ipa) Wikipedia G2P | independent cross-engine (Univ. of the Basque Country) | PER `0.1384` folded (3k-sentence sample) |
+
+The WikiPron and HiTZ figures are the honest ones: a pure lattice with no
+lexicon, on proper-name-heavy and raw-Wikipedia text, where transcription
+conventions and multiple valid pronunciations account for much of the gap. That
+gap is exactly what the lexicon hook exists to close. Comparable open tools:
+**AhoTTS** (the EHU TTS front end) covers Standard Batua only; **espeak-ng**'s
+`eu` voice is single-dialect and rule-thin — euskaphone's contribution is the
+eight-lect coverage, the sourced vigesimal numerals, and the code-switch
+nativization, over a lattice shared across the whole Iberian family.
+
+## License
+
+Apache-2.0.

euskaphone-0.1.0a2/README.md

@@ -0,0 +1,187 @@
+# euskaphone
+
+Dialect-aware Basque (Euskara) text-to-IPA phonemizer — a TTS frontend built on
+the shared [orthography2ipa](https://github.com/TigreGotico/orthography2ipa)
+pronunciation lattice. euskaphone is the Basque sibling of
+[tugaphone](https://github.com/TigreGotico/tugaphone) (Portuguese) and
+[mwl_phonemizer](https://github.com/TigreGotico/mwl_phonemizer) (Mirandese), and
+is offered to the Basque research and speech-technology community as an open,
+inspectable, source-cited pipeline.
+
+A dialect *is* an orthography2ipa Basque lect spec: the spec's grapheme table,
+allophony and cross-word sandhi produce the dialect's phonology directly — the
+apical/laminal sibilant contrast, the affricates, Souletin aspiration and `/y/`.
+euskaphone adds only the stages orthography2ipa leaves to the caller.
+
+## Install
+
+```bash
+pip install euskaphone
+```
+
+## Quickstart
+
+```python
+from euskaphone import EuskaPhonemizer
+
+ph = EuskaPhonemizer()
+ph.phonemize_sentence("Zazpi katu zuri ikusi ditut.")          # Batua (default)
+# 's̻as̻pi katu s̻uɾi ikus̺i ditut'
+
+ph.phonemize_sentence("Hotza egiten du gaur mendian.", "souletin")
+# 'hots̻a eɡiten dy ɡauɾ mendian'   (Souletin: aspiration, /y/)
+```
+
+## Dialects
+
+Eight lects, selectable by BCP-47 code or by a human-readable alias:
+
+| code | dialect | aliases |
+|------|---------|---------|
+| `eu` | Standard Basque | `batua`, `standard` |
+| `eu-x-bizkaiera` | Biscayan | `biscayan`, `western` |
+| `eu-x-gipuzkera` | Gipuzkoan | `guipuzcoan`, `central` |
+| `eu-x-lapurtera` | Lapurdian | `labourdin` |
+| `eu-x-nafarra-garaia` | High Navarrese | `high-navarrese` |
+| `eu-x-nafarra-beherea` | Low Navarrese | `low-navarrese` |
+| `eu-x-zuberera` | Souletin | `souletin`, `xiberotarra` |
+| `eu-x-erronkariera` | Roncalese (†) | `roncalese` |
+
+## The three things euskaphone adds
+
+### 1. Vigesimal number normalization (the flagship)
+
+Basque cardinals are **base-20**: `hogei` (20), `berrogei` (40 = 2×20),
+`hirurogei` (60), `laurogei` (80); 30/50/70/90 are the preceding twenty *plus
+ten*; and the copulative `eta` ("and") contracts to `-ta` on the twenties.
+
+```python
+from euskaphone.number_utils import BasqueNumberParser, normalize_numbers
+
+p = BasqueNumberParser("eu")
+p.cardinal(31)     # 'hogeita hamaika'   (20-and-11)
+p.cardinal(1936)   # 'mila bederatziehun eta hogeita hamasei'
+p.ordinal(16)      # 'hamaseigarren'
+
+# case-suffixed numerals and clock time in running text (declension on the
+# last element of the numeral phrase)
+normalize_numbers("1936ko gerra", "eu")   # '… hogeita hamaseiko gerra'
+normalize_numbers("20:00etan", "eu")      # 'hogeietan'
+```
+
+Every base form is cited to **Euskaltzaindia Araua 7** (cardinals) and
+**Araua 18** (ordinals), and each is tagged attested-in-source vs derived-by-rule
+in `euskaphone.number_utils` (the `ATTESTED` / `DERIVED` sets). One notable
+correction the sources force: Araua 7 records `bost` (not `bortz`) for Zuberoa
+and most of Low Navarre, so euskaphone keeps `bost` everywhere by default and
+offers the `bortz` series only for Lapurdian — null beats a wrong dialect swap.
+See [`docs/numbers.md`](docs/numbers.md).
+
+### 2. Code-switch handling
+
+Real Basque text embeds Spanish (Hegoalde), French (Iparralde) and — in the
+tech/music/media register — English. Word-level detection identifies the embedded
+material, classifies each contact word **per word** among `es`/`fr`/`en`, routes
+it through the orthography2ipa `es-ES`/`fr-FR`/`en-US` lattice, and **nativizes**
+the result onto the Basque inventory (project every foreign phone onto its
+nearest Basque phone — never drop, always project). The `contact` parameter is
+`auto` (per-word detection), `es`, `fr`, `en`, or `none`.
+
+Detection prefers a small bundled **char-Markov language detector** (Basque /
+Spanish / French / English, ~180 KB total, scored by `markovonnx`; install with
+`euskaphone[langdetect]`) and falls back to an orthographic heuristic when the
+models are unavailable. Basque is the in-language default: a word is routed out
+of Basque only when a foreign model beats the Basque model by a clear margin (and
+short, plausibly-native words need orthographic corroboration), so a weak signal
+never misroutes a native word.
+
+```python
+ph.phonemize_sentence("Madrilen Plaza Mayor ikusi dut.", "eu")
+# '… plas̻a majoɾ …'  (Spanish routed + nativized: no θ, no stress)
+
+ph.phonemize_sentence("Streaming plataforma berria erabili dugu.")
+# 'strimin platafoɾma …'  (English routed + nativized onto the 5-vowel system)
+
+ph.phonemize_sentence("Maison Rouge etxean.", "souletin")
+# continental dialect → French contact by default
+```
+
+See [`docs/codeswitch.md`](docs/codeswitch.md).
+
+### 3. Lexicon hook + shipped lexicons
+
+`register_lexicon(dialect, source)` registers a proper-name/loan pronunciation
+table (the orthography2ipa lexicon contract: a `word<TAB>ipa` path, URL or
+`hf://` id); a covered word bypasses the lattice.
+
+Two lexicons ship built-in: a curated **Euskaltzaindia toponym seed** (on by
+default, `EuskaPhonemizer(toponyms=False)` to opt out) and an opt-in **HiTZ
+proper-noun overlay** (`EuskaPhonemizer(lexicon="hitz")`) that carries a
+benchmark circularity caveat. A caller's own lexicon always wins.
+See [`docs/lexicons.md`](docs/lexicons.md).
+
+### 4. Orthographic normalization
+
+Before the lattice runs, everything written as a symbol, abbreviation, Roman
+numeral or numeric date is spelled into Basque words
+(`euskaphone.normalize.normalize_text`, wired in as the orthography2ipa
+`normalize` stage):
+
+```python
+from euskaphone.normalize import normalize_text
+
+normalize_text("XX. mendean %20 igo da", "eu")
+# 'hogeigarren mendean ehuneko hogei igo da'
+normalize_text("Luis XIV.a errege zen", "eu")     # '… hamalaugarrena …'
+normalize_text("Sarrera €5eko da", "eu")          # '… bost euroko …'
+normalize_text("15/01/2024", "eu")   # 'bi mila eta hogeita lauko urtarrilaren hamabostean'
+```
+
+Roman-numeral ordinals (`XX.` → `hogeigarren`) and monarch numerals
+(`Luis XIV.a` → `hamalaugarrena`), a cited abbreviation list
+(`etab.` → `eta abar`), unit/currency/percent symbols with Basque word order and
+declension (`%5` and `5%` both → `ehuneko bost`), and numeric dates — each cited
+to Euskaltzaindia (Araua 18/37/196/197) and the EIMA *Ortotipografia* guide. The
+abbreviation and unit tables are expandable data files
+(`euskaphone/data/*.tsv`). See [`docs/normalization.md`](docs/normalization.md).
+
+### No homograph subsystem — by design
+
+Basque orthography is near-phonemic: a grapheme's reading is essentially fixed
+and sense-independent. Unlike tugaphone's Portuguese (which needs `bifonia` to
+resolve heterophonic homographs), euskaphone deliberately ships **no** homograph
+stage. This is a scope decision, documented so it is not mistaken for a gap.
+
+## OVOS plugin
+
+```python
+from euskaphone.plugin import EuskaphoneG2PPlugin
+EuskaphoneG2PPlugin("souletin").transcribe("kaixo mundua")
+```
+
+Registered under the `opm.g2p` entry-point group as `euskaphone`.
+
+## How it measures up
+
+euskaphone drives the shared orthography2ipa lattice, so it is only as accurate
+as that lattice — these numbers measure the lattice, honestly labelled. Run them
+with `python scripts/benchmark.py [--hitz]`.
+
+| gold | kind | figure |
+|------|------|--------|
+| orthography2ipa eu gold (166 rows, 8 lects) | **regression fixture** (same lattice made it) | PER `0.0000` — proves the lattice is untouched, *not* accuracy |
+| [WikiPron](https://github.com/CUNY-CL/wikipron) `eus_latn` broad | independent word gold | PER `0.0749`, word-acc `0.4563` (full set, 20,115 words) |
+| [HiTZ/EHU](https://huggingface.co/datasets/HiTZ/wikipedia_basque_ipa) Wikipedia G2P | independent cross-engine (Univ. of the Basque Country) | PER `0.1384` folded (3k-sentence sample) |
+
+The WikiPron and HiTZ figures are the honest ones: a pure lattice with no
+lexicon, on proper-name-heavy and raw-Wikipedia text, where transcription
+conventions and multiple valid pronunciations account for much of the gap. That
+gap is exactly what the lexicon hook exists to close. Comparable open tools:
+**AhoTTS** (the EHU TTS front end) covers Standard Batua only; **espeak-ng**'s
+`eu` voice is single-dialect and rule-thin — euskaphone's contribution is the
+eight-lect coverage, the sourced vigesimal numerals, and the code-switch
+nativization, over a lattice shared across the whole Iberian family.
+
+## License
+
+Apache-2.0.